Allo

Change eSIM tier

Moves an eSIM to another data tier. An upgrade is charged now, prorated for the rest of the billing period: Allo draws on your prepaid credit first, then…

PUT/v2/api/partner/esims/{id}/tier

Moves an eSIM to another data tier. An upgrade is charged now and adds the extra data within about a minute. A downgrade applies at the end of the period you already paid for.

Request

  • tier is required: a tiers[].code from Get eSIM offer, for example ESIM_20GB. ESIM is the tier with no mobile data. An unknown code fails with INVALID_ESIM_TIER.
  • The eSIM must be ACTIVE. While it is still provisioning, the request fails with ESIM_NOT_READY.

Response

statusWhat it means
ACTIVEThe eSIM is already on this tier. Nothing is charged.
PENDINGUpgrade. Allo charges it now, and the extra data is added within about a minute once the payment is confirmed.
SCHEDULEDDowngrade. The eSIM keeps its current tier until effective_at, the end of the period already paid, then switches to the new tier. Nothing is refunded.

effective_at is null unless status is SCHEDULED. Get eSIM returns the current tier, the scheduled downgrade in scheduled_tier and scheduled_tier_at, and the month's allowance in data.allowance_mb.

An upgrade raises the allowance, so partner.esim.data_low and partner.esim.data_exhausted can be sent again as the eSIM nears the new allowance.

Billing

  • An upgrade is charged on the subscription you pay for the account, prorated for the rest of the current billing period, with your partner discount applied. The subscription then renews at the new tier's price.
  • 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 upgrade 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.
  • A downgrade charges nothing and refunds nothing.

Retries

Send an Idempotency-Key header (8 to 100 letters, digits, - or _, for example a UUID) and reuse it when you retry the same change. Retrying with the same key does not charge you twice. A key in another format fails with INVALID_IDEMPOTENCY_KEY.

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_TIER_CHANGE_CONFLICTA downgrade is already scheduled for this eSIM. It cannot be replaced until it applies, at scheduled_tier_at.
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-Keystring

Optional. 8 to 100 letters, digits, - or _, for example a UUID. Retrying with the same key does not charge you twice.

Body

tierstringrequired

A tier code from Get eSIM offer. ESIM is the tier with no mobile data.

Responses

200Tier change accepted
dataobject
4 fields
esim_idstring

The eSIM id (eso-*).

tierstring

The tier you asked for.

statusenum<string>

ACTIVE: the eSIM is already on this tier, nothing is charged. PENDING: upgrade charged, the extra data is added once the payment is confirmed. SCHEDULED: downgrade, it applies at effective_at.

ACTIVEPENDINGSCHEDULED

effective_atstring<date-time> | null

When a scheduled downgrade applies: the end of the period already paid. null unless status is SCHEDULED.

400Validation error: MISSING_FIELD (tier), INVALID_ESIM_TIER 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), already has a downgrade scheduled (ESIM_TIER_CHANGE_CONFLICT), 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