Core Concepts

Before diving into the API, understand these core concepts that form the foundation of every Bitrefill integration.

Products

A product represents something you can purchase — a gift card brand, mobile operator, or eSIM plan.

{
  "id": "amazon-us",
  "name": "Amazon US",
  "type": "gift_card",
  "country": "US",
  "currency": "USD"
}

Products define what you can buy, but not how much. That's where denominations come in.

Denominations: Packages vs Ranges

Products offer denominations in two ways:

Packages (Fixed Values)

Some products have fixed denominations. You must purchase one of the available values.

{
  "packages": [
    { "package_id": "amazon-us<&>25", "value": 25 },
    { "package_id": "amazon-us<&>50", "value": 50 },
    { "package_id": "amazon-us<&>100", "value": 100 }
  ]
}

To purchase, use the package_id in your invoice request.

Ranges (Flexible Values)

Other products accept any value within a range.

{
  "range": {
    "min": 10,
    "max": 200,
    "step": 1
  }
}

• min — Minimum purchase amount
• max — Maximum purchase amount
• step — Allowed increment (e.g., step of 5 means you can buy 10, 15, 20... not 12)

To purchase, specify the value directly in your invoice request.

Some products have both packages AND a range. You can use either approach.

Product Types

Invoices

An invoice is a payment request for one or more products. Creating an invoice is the first step in making a purchase.

{
  "id": "inv_abc123",
  "status": "unpaid",
  "payment": {
    "method": "bitcoin",
    "address": "bc1q...",
    "price": 0.00123456
  },
  "orders": [
    { "id": "ord_xyz789", "status": "created" }
  ]
}

Invoice Statuses

Invoice Flow

stateDiagram-v2
    [*] --> unpaid: Invoice created
    unpaid --> payment_detected: Payment seen
    payment_detected --> payment_confirmed: Confirmations received
    payment_confirmed --> pending: Processing
    pending --> complete: All delivered
    unpaid --> denied: Rejected
    payment_detected --> payment_error: Error

Multiple Products per Invoice

An invoice can contain multiple products. Each product becomes a separate order within the invoice.

{
  "products": [
    { "product_id": "amazon-us", "value": 50 },
    { "product_id": "spotify-us", "package_id": "spotify-us<&>10" },
    { "product_id": "steam-us", "value": 25, "quantity": 2 }
  ]
}

This creates one invoice with 4 orders (2 Steam cards due to quantity: 2).

Orders

An order represents a single product purchase within an invoice. When an invoice is paid, each order is processed and delivered individually.

{
  "id": "ord_xyz789",
  "status": "delivered",
  "product": {
    "id": "amazon-us",
    "name": "Amazon US",
    "value": 50
  },
  "redemption_info": {
    "code": "ABCD-EFGH-IJKL",
    "link": "https://redeem.amazon.com/..."
  }
}

Order Statuses

Redemption Info

Once an order is delivered, the redemption_info object contains what the end user needs:

Not all products return the same fields. Gift cards typically have code or link. Phone top-ups may have no redemption info — the balance is added directly to the phone.

eSIMs

eSIMs are digital SIM cards that provide mobile data without a physical SIM. They work differently from regular products.

eSIM Products

eSIM products represent data plans for specific regions:

{
  "id": "bitrefill-esim-europe",
  "name": "Bitrefill eSIM Europe",
  "packages": [
    { "package_id": "bitrefill-esim-europe<&>1GB, 7 Days", "value": "1GB, 7 Days" },
    { "package_id": "bitrefill-esim-europe<&>5GB, 30 Days", "value": "5GB, 30 Days" }
  ]
}

Note that eSIM package values are strings describing data and duration, not numbers.

Initial Purchase vs Top-Up

• Initial purchase — Creates a new eSIM with a data bundle
• Top-up — Adds a data bundle to an existing eSIM

For top-ups, include the esim_id (ICCID) in your invoice request:

{
  "product_id": "bitrefill-esim-europe",
  "value": "5GB, 30 Days",
  "esim_id": "4058965632381351147"
}

eSIM Object

After purchase, you get an eSIM object:

{
  "id": "4058965632381351147",
  "rsp_url": "...",
  "pin": "1234",
  "barcode_value": "LPA:1$...",
  "installed": false,
  "package_history": [
    {
      "package_name": "1GB, 7 Days",
      "data_mb": 1000,
      "status": "active",
      "remaining_quantity": 500000000
    }
  ]
}

Key fields: