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

# Changer le palier d'une eSIM

> 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]
>
> **Scope requis :** `PARTNER`

Fait passer une eSIM à un autre palier de données. Une montée de palier est débitée tout de suite et ajoute les données en plus en une minute environ. Une baisse de palier s'applique à la fin de la période déjà payée.

## Requête

* `tier` est requis : un `tiers[].code` renvoyé par [Obtenir l'offre eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim-offer.md), par exemple `ESIM_20GB`. `ESIM` est le palier sans données mobiles. Un code inconnu échoue avec `INVALID_ESIM_TIER`.
* L'eSIM doit être `ACTIVE`. Tant qu'elle est en cours de provisionnement, la requête échoue avec `ESIM_NOT_READY`.

## Réponse

| `status` | Signification |
| - | - |
| `ACTIVE` | L'eSIM est déjà sur ce palier. Rien n'est débité. |
| `PENDING` | Montée de palier. Allo la débite tout de suite, et les données en plus sont ajoutées en une minute environ, une fois le paiement confirmé. |
| `SCHEDULED` | Baisse de palier. L'eSIM garde son palier actuel jusqu'à `effective_at`, la fin de la période déjà payée, puis passe au nouveau palier. Rien n'est remboursé. |

`effective_at` vaut `null` sauf si `status` vaut `SCHEDULED`. [Obtenir une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim.md) renvoie le `tier` actuel, la baisse prévue dans `scheduled_tier` et `scheduled_tier_at`, et le quota du mois dans `data.allowance_mb`.

Une montée de palier relève le quota : [`partner.esim.data_low`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimdata_low) et [`partner.esim.data_exhausted`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimdata_exhausted) peuvent alors être envoyés à nouveau quand l'eSIM approche du nouveau quota.

## Facturation

* Une montée de palier est facturée sur l'abonnement que vous payez pour le compte, au prorata du reste de la période de facturation en cours, avec votre remise partenaire appliquée. L'abonnement se renouvelle ensuite au prix du nouveau palier.
* Allo prélève d'abord votre [crédit prépayé](https://help.withallo.com/fr/v2/api-reference/partner/get-credit.md), puis débite le reste sur votre carte enregistrée. Allo ne facture jamais votre client.
* Si votre crédit prépayé ne couvre pas la montée de palier et qu'aucune carte n'est enregistrée, la requête échoue avec `402 PARTNER_CREDIT_INSUFFICIENT`.
* Une carte refusée, ou une carte qui exige 3D Secure, échoue avec `402 ESIM_PAYMENT_FAILED`. Une validation 3D Secure est impossible via l'API : Allo annule la tentative et rien ne reste en attente. Réessayez avec une autre carte, mise à jour dans le [portail partenaire](https://help.withallo.com/fr/support/partner-portal.md), ou après avoir rechargé votre crédit prépayé.
* Une baisse de palier ne débite rien et ne rembourse rien.

## Nouvelles tentatives

Envoyez un en-tête `Idempotency-Key` (8 à 100 lettres, chiffres, `-` ou `_`, par exemple un UUID) et réutilisez-le pour réessayer le même changement. Une nouvelle tentative avec la même clé ne vous débite pas deux fois. Une clé dans un autre format échoue avec `INVALID_IDEMPOTENCY_KEY`.

## Erreurs propres à l'eSIM

| Code | Signification |
| - | - |
| `ESIM_NOT_READY` | L'eSIM est encore en cours de provisionnement. Attendez [`partner.esim.ready`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimready), puis réessayez. |
| `ESIM_NOT_ACTIVE` | L'eSIM a été supprimée, ou le numéro a une commande d'eSIM plus récente. Seule la dernière eSIM du numéro peut être modifiée : utilisez son id, ou commandez une nouvelle eSIM avec [Commander une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/order-esim.md). |
| `ESIM_TIER_CHANGE_CONFLICT` | Une baisse de palier est déjà prévue pour cette eSIM. Elle ne peut pas être remplacée avant de s'appliquer, à `scheduled_tier_at`. |
| `ESIM_SUBSCRIPTION_CONFLICT` | L'abonnement que vous payez pour le compte ne peut pas être débité pour des eSIM pour le moment. Si l'erreur indique `retryable: true`, réessayez dans quelques 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.