Skip to main content
PUT
Change eSIM tier
Required scope: PARTNER
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

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

Authorizations

Authorization
string
header
required

Headers

Idempotency-Key
string

Optional. 8 to 100 letters, digits, - or _, for example a UUID. Retrying with the same key 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
tier
string
required

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

Example:

"ESIM_20GB"

Response

Tier change accepted

data
object