# 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`

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

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](/docs/white-label/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

| `status` | What it means |
|----------|---------------|
| `ACTIVE` | The eSIM is already on this tier. Nothing is charged. |
| `PENDING` | Upgrade. Allo charges it now, and the extra data is added within about a minute once the payment is confirmed. |
| `SCHEDULED` | Downgrade. 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](/docs/white-label/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`](/docs/webhooks/event-catalog#partneresimdata_low) and [`partner.esim.data_exhausted`](/docs/webhooks/event-catalog#partneresimdata_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](/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 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](/help/support/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

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