# Buy eSIM top-up

> Buys a data top-up for an eSIM. The top-up is charged once: Allo draws on your prepaid credit first, then charges your card on file. Its data is added to the…

`POST /v2/api/partner/esims/{id}/topups`

<Note>
**Required scope:** `PARTNER`
</Note>

Buys extra mobile data for an eSIM, on top of its tier. A top-up is a one-off charge. Its data counts for the current calendar month only (Paris time), and unused data lapses at the end of that month.

When an eSIM reaches its allowance, mobile data stops until the next month or until you buy a top-up. Calls and SMS keep working, and the line is never billed for data beyond the allowance. Allo sends [`partner.esim.data_low`](/docs/webhooks/event-catalog#partneresimdata_low) at 80% of the allowance and [`partner.esim.data_exhausted`](/docs/webhooks/event-catalog#partneresimdata_exhausted) at 100%, so you can offer your client a top-up in time.

## Request

- The `Idempotency-Key` header is required: see [Retries](#retries).
- `code` is required: a `top_ups[].code` from [Get eSIM offer](/docs/white-label/get-esim-offer).
- The eSIM must be `ACTIVE`. While it is still provisioning, the request fails with `ESIM_NOT_READY`.

| `code` | Data added |
|--------|------------|
| `TOPUP_5GB` | 5 GB (5120 MB) |
| `TOPUP_10GB` | 10 GB (10240 MB) |
| `TOPUP_20GB` | 20 GB (20480 MB) |

An unknown code fails with `INVALID_ESIM_TOPUP`. You can buy several top-ups for the same eSIM in the same month: their data adds up.

## Response

| `status` | What it means |
|----------|---------------|
| `PENDING` | Allo charged the top-up. Its data is added to the eSIM once the payment is confirmed, and [Get eSIM](/docs/white-label/get-esim) then shows it in `data.allowance_mb`. |
| `ACTIVE` | A retry with the same `Idempotency-Key` of a top-up already added. Nothing is charged again. |

## Billing

- The price is the one [Get eSIM offer](/docs/white-label/get-esim-offer) returns for the account: before tax, in the currency of the subscription you pay for the account.
- Allo draws on your [prepaid credit](/docs/partner/get-credit) first, then charges your card on file for the rest. Allo never charges your client.
- If your prepaid credit does not cover the top-up and you have no card on file, the request fails with `402 PARTNER_CREDIT_INSUFFICIENT`.
- A declined card, or a card that requires 3D Secure, fails with `402 ESIM_PAYMENT_FAILED`. A 3D Secure check cannot happen over the API, so Allo cancels the attempt and nothing stays pending. Retry with another card, updated in the [partner portal](/help/support/partner-portal), or after you top up your prepaid credit.

## Retries

The `Idempotency-Key` header is required on this endpoint, so a retry can never charge you twice. Send a new UUID for each top-up, and the same one when you retry that top-up.

- Without the header, the request fails with `400 IDEMPOTENCY_KEY_REQUIRED`.
- The key is 8 to 100 letters, digits, `-` or `_`. A key in another format fails with `400 INVALID_IDEMPOTENCY_KEY`.
- A key already used on this eSIM for a top-up with another `code` fails with `409 IDEMPOTENCY_KEY_ALREADY_USED`. Send a new key for a new top-up.

## Errors specific to this eSIM

| Code | What it means |
|------|---------------|
| `ESIM_NOT_READY` | The eSIM is still provisioning. Wait for [`partner.esim.ready`](/docs/webhooks/event-catalog#partneresimready), then retry. |
| `ESIM_NOT_ACTIVE` | The eSIM was deleted, or the number has a newer eSIM order. Only the number's latest eSIM can be changed: use its id, or order a new eSIM with [Order eSIM](/docs/white-label/order-esim). |
| `ESIM_TOPUP_PENDING` | Another top-up for this eSIM is still being paid. Always `retryable: true`. Retry in a few minutes, or resume the earlier purchase with its `Idempotency-Key`. |
| `ESIM_SUBSCRIPTION_CONFLICT` | The subscription you pay for the account cannot be charged for eSIMs right now. When the error is `retryable: true`, retry in a few minutes. |
