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

# Acheter une recharge de données eSIM

> Buys a data top-up for an eSIM. The top-up is charged once: Allo draws on your prepaid credit first, then charges your card on file. Its data is added to the eSIM once the payment is confirmed, for the current calendar month (Paris time). Unused data lapses at the end of that month. The `Idempotency-Key` header is required: send a new UUID for each top-up and the same one when you retry it. A card that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED` and the attempt is cancelled. Only the number's latest eSIM can be topped up. Requires the `PARTNER` scope.

> [!NOTE]
>
> **Scope requis :** `PARTNER`

Achète des données mobiles en plus pour une eSIM, au-delà de son palier. Une recharge est débitée une seule fois. Ses données comptent pour le mois civil en cours uniquement (heure de Paris), et les données non utilisées sont perdues à la fin de ce mois.

Quand une eSIM atteint son quota, les données mobiles s'arrêtent jusqu'au mois suivant ou jusqu'à l'achat d'une recharge. Les appels et les SMS continuent de fonctionner, et la ligne n'est jamais facturée pour des données au-delà du quota. Allo envoie [`partner.esim.data_low`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimdata_low) à 80 % du quota et [`partner.esim.data_exhausted`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimdata_exhausted) à 100 %, pour que vous puissiez proposer une recharge à votre client à temps.

## Requête

* L'en-tête `Idempotency-Key` est obligatoire : voir [Nouvelles tentatives](#nouvelles-tentatives).
* `code` est requis : un `top_ups[].code` renvoyé par [Obtenir l'offre eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim-offer.md).
* L'eSIM doit être `ACTIVE`. Tant qu'elle est en cours de provisionnement, la requête échoue avec `ESIM_NOT_READY`.

| `code` | Données ajoutées |
| - | - |
| `TOPUP_5GB` | 5 Go (5120 Mo) |
| `TOPUP_10GB` | 10 Go (10240 Mo) |
| `TOPUP_20GB` | 20 Go (20480 Mo) |

Un code inconnu échoue avec `INVALID_ESIM_TOPUP`. Vous pouvez acheter plusieurs recharges pour la même eSIM dans le même mois : leurs données s'additionnent.

## Réponse

| `status` | Signification |
| - | - |
| `PENDING` | Allo a débité la recharge. Ses données sont ajoutées à l'eSIM une fois le paiement confirmé, et [Obtenir une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim.md) les affiche alors dans `data.allowance_mb`. |
| `ACTIVE` | Une nouvelle tentative, avec la même `Idempotency-Key`, d'une recharge déjà ajoutée. Rien n'est débité à nouveau. |

## Facturation

* Le prix est celui que renvoie [Obtenir l'offre eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim-offer.md) pour le compte : hors taxes, dans la devise de l'abonnement que vous payez pour le compte.
* 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 recharge 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é.

## Nouvelles tentatives

L'en-tête `Idempotency-Key` est obligatoire sur cet endpoint, pour qu'une nouvelle tentative ne vous débite jamais deux fois. Envoyez un nouvel UUID pour chaque recharge, et le même quand vous réessayez cette recharge.

* Sans l'en-tête, la requête échoue avec `400 IDEMPOTENCY_KEY_REQUIRED`.
* La clé compte 8 à 100 lettres, chiffres, `-` ou `_`. Une clé dans un autre format échoue avec `400 INVALID_IDEMPOTENCY_KEY`.
* Une clé déjà utilisée sur cette eSIM pour une recharge avec un autre `code` échoue avec `409 IDEMPOTENCY_KEY_ALREADY_USED`. Envoyez une nouvelle clé pour une nouvelle recharge.

## 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_TOPUP_PENDING` | Une autre recharge pour cette eSIM est encore en cours de paiement. Toujours `retryable: true`. Réessayez dans quelques minutes, ou reprenez l'achat précédent avec sa `Idempotency-Key`. |
| `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 POST /v2/api/partner/esims/{id}/topups
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}/topups:
    post:
      tags:
        - White label
      summary: Buy eSIM top-up
      description: >-
        Buys a data top-up for an eSIM. The top-up is charged once: Allo draws
        on your prepaid credit first, then charges your card on file. Its data
        is added to the eSIM once the payment is confirmed, for the current
        calendar month (Paris time). Unused data lapses at the end of that
        month. The `Idempotency-Key` header is required: send a new UUID for
        each top-up and the same one when you retry it. A card that requires 3D
        Secure is refused with `ESIM_PAYMENT_FAILED` and the attempt is
        cancelled. Only the number's latest eSIM can be topped up. Requires the
        `PARTNER` scope.
      operationId: buyPartnerEsimTopUp
      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: true
          schema:
            type: string
            pattern: ^[A-Za-z0-9_-]{8,100}$
          description: >-
            Required. 8 to 100 letters, digits, `-` or `_`, for example a UUID.
            Send a new key for each top-up and the same key when you retry it:
            Allo does not charge you twice.
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - code
              properties:
                code:
                  type: string
                  description: A top-up `code` from Get eSIM offer.
                  example: TOPUP_5GB
            example:
              code: TOPUP_5GB
      responses:
        '201':
          description: Top-up bought
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      esim_id:
                        type: string
                        description: The eSIM id (`eso-*`).
                        example: eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61
                      code:
                        type: string
                        description: The top-up you bought.
                        example: TOPUP_5GB
                      data_mb:
                        type: integer
                        format: int64
                        description: Mobile data the top-up adds, in MB.
                        example: 5120
                      status:
                        type: string
                        enum:
                          - PENDING
                          - ACTIVE
                        description: >-
                          `PENDING`: charged, the data is added once the payment
                          is confirmed. `ACTIVE`: a retry with the same
                          `Idempotency-Key` of a top-up already added.
                        example: PENDING
              example:
                data:
                  esim_id: eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61
                  code: TOPUP_5GB
                  data_mb: 5120
                  status: PENDING
        '400':
          description: >-
            Validation error: MISSING_FIELD (`code`), INVALID_ESIM_TOPUP,
            IDEMPOTENCY_KEY_REQUIRED (no `Idempotency-Key` header) 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), another top-up for
            it is still being paid (ESIM_TOPUP_PENDING, retryable), the
            `Idempotency-Key` was already used for another top-up on this eSIM
            (IDEMPOTENCY_KEY_ALREADY_USED), 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.