Skip to main content
POST
Buy eSIM top-up
Required scope: PARTNER
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.
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

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

Authorizations

Authorization
string
header
required

Headers

Idempotency-Key
string
required

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.

Pattern: ^[A-Za-z0-9_-]{8,100}$

Path Parameters

id
string
required

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

Body

application/json
code
string
required

A top-up code from Get eSIM offer.

Example:

"TOPUP_5GB"

Response

Top-up bought

data
object