> ## Documentation Index
> Fetch the complete documentation index at: https://help.withallo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 charges your card on file. The extra data is added within about a minute once the payment is confirmed. A downgrade is scheduled for the end of the period already paid, and nothing is refunded. A card that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED` and the attempt is cancelled. Only the number's latest eSIM can change tier. Requires the `PARTNER` scope.

> [!NOTE]
>
> **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](https://help.withallo.com/en/v2/api-reference/white-label/get-esim-offer.md), 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](https://help.withallo.com/en/v2/api-reference/white-label/get-esim.md) 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`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneresimdata_low) and [`partner.esim.data_exhausted`](https://help.withallo.com/en/v2/api-reference/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](https://help.withallo.com/en/v2/api-reference/partner/get-credit.md) 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](https://help.withallo.com/en/support/partner-portal.md), 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`](https://help.withallo.com/en/v2/api-reference/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](https://help.withallo.com/en/v2/api-reference/white-label/order-esim.md). |
| `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. |


## OpenAPI

````yaml PUT /v2/api/partner/esims/{id}/tier
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Fax
    description: >-
      Send a PDF as a fax from an Allo line with fax turned on. Sent and
      received faxes appear in conversation items.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
  - name: AI Receptionist
    description: >-
      Read and write the AI receptionist configuration of a phone line: business
      details, voice, prompt, capabilities, business hours, transfer rules,
      scheduling calendars and knowledge sources.
  - name: Inboxes
    description: >-
      Personal inboxes: saved views of one or more lines, optionally narrowed to
      phone-menu options, with their own filters and notification setting.
paths:
  /v2/api/partner/esims/{id}/tier:
    put:
      tags:
        - White label
      summary: Change eSIM tier
      description: >-
        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 charges your card on file. The extra data is added within
        about a minute once the payment is confirmed. A downgrade is scheduled
        for the end of the period already paid, and nothing is refunded. A card
        that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED` and the
        attempt is cancelled. Only the number's latest eSIM can change tier.
        Requires the `PARTNER` scope.
      operationId: changePartnerEsimTier
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The eSIM id returned by Order eSIM (`eso-*`).
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            pattern: ^[A-Za-z0-9_-]{8,100}$
          description: >-
            Optional. 8 to 100 letters, digits, `-` or `_`, for example a UUID.
            Retrying with the same key does not charge you twice.
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tier
              properties:
                tier:
                  type: string
                  description: >-
                    A tier `code` from Get eSIM offer. `ESIM` is the tier with
                    no mobile data.
                  example: ESIM_20GB
            example:
              tier: ESIM_20GB
      responses:
        '200':
          description: Tier change accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      esim_id:
                        type: string
                        description: The eSIM id (`eso-*`).
                        example: eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61
                      tier:
                        type: string
                        description: The tier you asked for.
                        example: ESIM_20GB
                      status:
                        type: string
                        enum:
                          - ACTIVE
                          - PENDING
                          - SCHEDULED
                        description: >-
                          `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`.
                        example: PENDING
                      effective_at:
                        type: string
                        format: date-time
                        nullable: true
                        description: >-
                          When a scheduled downgrade applies: the end of the
                          period already paid. `null` unless `status` is
                          `SCHEDULED`.
                        example: null
              example:
                data:
                  esim_id: eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61
                  tier: ESIM_20GB
                  status: PENDING
                  effective_at: null
        '400':
          description: >-
            Validation error: MISSING_FIELD (`tier`), INVALID_ESIM_TIER or
            INVALID_IDEMPOTENCY_KEY.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '402':
          description: >-
            Billing 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.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '403':
          description: The API key lacks the PARTNER scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '404':
          description: >-
            No 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).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '409':
          description: >-
            The 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).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '429':
          $ref: '#/components/responses/ApiRateLimited'
        '500':
          description: >-
            The eSIM's data cannot be changed right now (ESIM_UNAVAILABLE). The
            message gives the reason.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
      security:
        - ApiKeyAuth: []
components:
  responses:
    ApiUnauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiRateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            request_id:
              type: string
            retry_after_seconds:
              type: integer
              nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.