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

# Buy eSIM top-up

> 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]
>
> **Required scope:** `PARTNER`

Buys extra mobile data for an eSIM, on top of its tier. A top-up is a one-off charge. Its data counts for the current calendar month only (Paris time), and unused data lapses at the end of that month.

When an eSIM reaches its allowance, mobile data stops until the next month or until you buy a top-up. Calls and SMS keep working, and the line is never billed for data beyond the allowance. Allo sends [`partner.esim.data_low`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneresimdata_low) at 80% of the allowance and [`partner.esim.data_exhausted`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneresimdata_exhausted) at 100%, so you can offer your client a top-up in time.

## Request

* The `Idempotency-Key` header is required: see [Retries](#retries).
* `code` is required: a `top_ups[].code` from [Get eSIM offer](https://help.withallo.com/en/v2/api-reference/white-label/get-esim-offer.md).
* The eSIM must be `ACTIVE`. While it is still provisioning, the request fails with `ESIM_NOT_READY`.

| `code` | Data added |
| - | - |
| `TOPUP_5GB` | 5 GB (5120 MB) |
| `TOPUP_10GB` | 10 GB (10240 MB) |
| `TOPUP_20GB` | 20 GB (20480 MB) |

An unknown code fails with `INVALID_ESIM_TOPUP`. You can buy several top-ups for the same eSIM in the same month: their data adds up.

## Response

| `status` | What it means |
| - | - |
| `PENDING` | Allo charged the top-up. Its data is added to the eSIM once the payment is confirmed, and [Get eSIM](https://help.withallo.com/en/v2/api-reference/white-label/get-esim.md) then shows it in `data.allowance_mb`. |
| `ACTIVE` | A retry with the same `Idempotency-Key` of a top-up already added. Nothing is charged again. |

## Billing

* The price is the one [Get eSIM offer](https://help.withallo.com/en/v2/api-reference/white-label/get-esim-offer.md) returns for the account: before tax, in the currency of the subscription you pay for the account.
* 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 top-up 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.

## Retries

The `Idempotency-Key` header is required on this endpoint, so a retry can never charge you twice. Send a new UUID for each top-up, and the same one when you retry that top-up.

* Without the header, the request fails with `400 IDEMPOTENCY_KEY_REQUIRED`.
* The key is 8 to 100 letters, digits, `-` or `_`. A key in another format fails with `400 INVALID_IDEMPOTENCY_KEY`.
* A key already used on this eSIM for a top-up with another `code` fails with `409 IDEMPOTENCY_KEY_ALREADY_USED`. Send a new key for a new top-up.

## 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_TOPUP_PENDING` | Another top-up for this eSIM is still being paid. Always `retryable: true`. Retry in a few minutes, or resume the earlier purchase with its `Idempotency-Key`. |
| `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 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.