eSIM: Top-Up an Existing eSIM

Disclaimer

Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.

A top-up (also called a recharge) adds a new data package to an eSIM that the end user has already installed — no new eSIM profile is issued. It uses the same FIXED_VALUE_PIN_PURCHASE product type and the same POST: Create a transaction asynchronously endpoint as a new eSIM purchase.

What decides "top-up" vs. "new purchase"

The presence of an ICCID in the request is the only switch:

When you include the ICCID in credit_party_identifier.account_number, the existing eSIM is reloaded with the selected plan. When you omit it, a brand-new eSIM is ordered and an activation profile is returned instead (see eSIM: FIXED_VALUE_PIN_PURCHASE).

Where to find the ICCID

The ICCID is returned when the eSIM is first purchased, in the completed transaction's pin.serial field (and, from v1.23.0, in metadata.profile.iccid). It is also available in the transaction status callback and in DT Shop, and can be found on the end user's device under eSIM settings.

Disclaimer

Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.

To top up an existing eSIM, call the POST: Create a transaction asynchronously endpoint with the target plan's product_id and the eSIM's ICCID in credit_party_identifier.account_number.

{
  "external_id": "ESIM-TOPUP-001",
  "product_id": 67890,
  "auto_confirm": true,
  "callback_url": "https://callback.example.com",
  "credit_party_identifier": {
    "account_number": "8948010000074885468"
  }
}

{
  "external_id": "ESIM-TOPUP-001",
  "product_id": 67890,
  "auto_confirm": false,
  "callback_url": "https://callback.example.com",
  "credit_party_identifier": {
    "account_number": "8948010000074885468"
  }
}

{
  "external_id": "ESIM-TOPUP-001",
  "product_id": 67890,
  "auto_confirm": true,
  "callback_url": "https://callback.example.com",
  "credit_party_identifier": {
    "account_number": "8948010000074885468"
  }
}

Disclaimer

Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.

Retrieve the final status either via your callback_url or by querying the transaction (GET: Query a transaction by ID / Query a list of transactions), exactly as for a new eSIM purchase.

A key difference from a new purchase: a top-up does not issue a new eSIM profile. The completed transaction therefore does not contain a new pin.code (activation code) or a metadata.profile object — the existing eSIM simply receives the additional data. The metadata object confirms the recharge with activation_type: TOP_UP and reports the newly activated balance.

{
  "benefits": [
    {
      "additional_information": null,
      "amount": {
        "base": 1,
        "promotion_bonus": 0,
        "total_excluding_tax": 1,
        "total_including_tax": 1
      },
      "type": "DATA",
      "unit": "GB",
      "unit_type": "DATA"
    }
  ],
  "callback_url": "https://callback.example.com",
  "confirmation_date": "2025-04-09T22:04:27.760931000Z",
  "confirmation_expiration_date": "2025-04-09T23:04:27.520011000Z",
  "creation_date": "2025-04-09T22:04:27.520011000Z",
  "credit_party_identifier": {
    "account_number": "8948010000074885468"
  },
  "external_id": "ESIM-TOPUP-001",
  "id": 2239249455,
  "metadata": {
    "type": "ESIM",
    "activation_type": "TOP_UP",
    "balance": {
      "size": { "amount": 1, "unit": "GB" },
      "validity": { "quantity": 7, "unit": "DAY" },
      "country_set": "EXX",
      "extended_data_policy": { "type": "STANDARD" }
    }
  },
  "operator_reference": "TX_2239249455",
  "prices": {
    "retail": null,
    "wholesale": {
      "amount": 3.49,
      "fee": 0,
      "unit": "USD",
      "unit_type": "CURRENCY"
    }
  },
  "product": {
    "description": "1 GB 7 days Europe Extended",
    "id": 67890,
    "name": "1 GB 7 days Europe Extended",
    "service": {
      "id": 13,
      "name": "eSIM",
      "subservice": null
    },
    "tags": null,
    "type": "FIXED_VALUE_PIN_PURCHASE"
  },
  "promotions": null,
  "rates": {
    "base": 1.14613180515759,
    "retail": -1,
    "wholesale": 1.14613180515759
  },
  "status": {
    "class": {
      "id": 7,
      "message": "COMPLETED"
    },
    "id": 70000,
    "message": "COMPLETED"
  }
}

Descriptions of Important Fields:

No metadata.profile on a top-up. Because no new eSIM profile is created, the completed top-up omits metadata.profile (and its activation_code, iccid, and installation links) as well as the top-level pin.code. The end user keeps using the eSIM they already installed. Only metadata.type, metadata.activation_type, and metadata.balance are guaranteed.

Disclaimer

Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.

After a top-up completes, you can confirm the eSIM's remaining data at any time by querying its balance with the ICCID — the same ad-hoc balance retrieval used for a newly purchased eSIM.

Request

{
  "service_id": 13,
  "credit_party_identifier": {
    "account_number": "8948010000074885468"
  }
}

Response (Relevant Fields)

[
    {
        "amount": 1,
        "expiration_date": null,
        "type": "DATA",
        "unit": "GB",
        "unit_type": "DATA"
    }
]

For the full balance-retrieval flow, see the Get eSIM Balance tab of the eSIM: FIXED_VALUE_PIN_PURCHASE guide.