Allo

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

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 at 80% of the allowance and partner.esim.data_exhausted at 100%, so you can offer your client a top-up in time.

Request

  • The Idempotency-Key header is required: see Retries.
  • code is required: a top_ups[].code from Get eSIM offer.
  • The eSIM must be ACTIVE. While it is still provisioning, the request fails with ESIM_NOT_READY.
codeData added
TOPUP_5GB5 GB (5120 MB)
TOPUP_10GB10 GB (10240 MB)
TOPUP_20GB20 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

statusWhat it means
PENDINGAllo charged the top-up. Its data is added to the eSIM once the payment is confirmed, and Get eSIM then shows it in data.allowance_mb.
ACTIVEA 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 returns for the account: before tax, in the currency of the subscription you pay for the account.
  • Allo draws on your prepaid 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, 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

CodeWhat it means
ESIM_NOT_READYThe eSIM is still provisioning. Wait for partner.esim.ready, then retry.
ESIM_NOT_ACTIVEThe 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.
ESIM_TOPUP_PENDINGAnother 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_CONFLICTThe subscription you pay for the account cannot be charged for eSIMs right now. When the error is retryable: true, retry in a few minutes.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

idstringrequired

The eSIM id returned by Order eSIM (eso-*).

Headers

Idempotency-Keystringrequired

Required. 8 to 100 letters, digits, - or _, for example a UUID. Send a new key for each top-up and the same key when you retry it: Allo does not charge you twice.

Body

codestringrequired

A top-up code from Get eSIM offer.

Responses

201Top-up bought
dataobject
4 fields
esim_idstring

The eSIM id (eso-*).

codestring

The top-up you bought.

data_mbinteger<int64>

Mobile data the top-up adds, in MB.

statusenum<string>

PENDING: charged, the data is added once the payment is confirmed. ACTIVE: a retry with the same Idempotency-Key of a top-up already added.

PENDINGACTIVE

400Validation error: MISSING_FIELD (code), INVALID_ESIM_TOPUP, IDEMPOTENCY_KEY_REQUIRED (no Idempotency-Key header) or INVALID_IDEMPOTENCY_KEY.
errorobject
401
402Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure, and the attempt was cancelled: retry with another payment method or after topping up your credit.
errorobject
403The API key lacks the PARTNER scope.
errorobject
404No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND), or the account the eSIM belongs to is deactivated (PARTNER_ACCOUNT_NOT_FOUND).
errorobject
409The eSIM is still provisioning (ESIM_NOT_READY), was deleted or is not the number's latest eSIM (ESIM_NOT_ACTIVE), another top-up for it is still being paid (ESIM_TOPUP_PENDING, retryable), the Idempotency-Key was already used for another top-up on this eSIM (IDEMPOTENCY_KEY_ALREADY_USED), or the subscription you pay for the account cannot be charged for eSIMs right now (ESIM_SUBSCRIPTION_CONFLICT).
errorobject
429
500The eSIM's data cannot be changed right now (ESIM_UNAVAILABLE). The message gives the reason.
errorobject