Submit top-up order - Airalo Developer Platform

To submit a top-up order:

Make a POST request to the endpoint URL {{url}}/{{version}}/orders/topups

Include a request body in the form of a FormData object, which contains the following required fields:

package_id: The ID of the top-up package you want to purchase

iccid: The ICCID of the eSIM for which you want to purchase the top-up package.

You can also include an optional description field to provide additional information about the order.

The API will respond with a JSON object containing the details of the order, including the package ID, quantity, price, and other information.

The complete workflow for buying a top-up package:

GET {{url}}/{{version}}/sims to see the list of purchased eSIMs

GET {{url}}/{{version}}/sims/:iccid/topups to see the list of available top-ups for the eSIMs

POST {{url}}/{{version}}/orders/topups with the proper "iccid" and "package_id" values to purchase a top-up

GET {{url}}/{{version}}/sims/:iccid/packages to see the list of all packages for the eSIM, including the original package and top-ups

For more informations, best practices visit our FAQ page: https://airalopartners.zendesk.com/hc/en-us/sections/13207524820893-FAQ

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Submit Top-up Order: 200 OK

application/json

Body

Example

{
    "data": {
        "id": 111,
        "code": "20251118-000111",
        "package_id": "change-7days-1gb-topup",
        "currency": "USD",
        "quantity": 1,
        "type": "topup",
        "description": "Topup (873000000000042542)",
        "esim_type": "local",
        "validity": 7,
        "package": "Change-1 GB - 7 Days",
        "data": "1 GB",
        "price": 4.5,
        "pricing_model": "net_pricing",
        "text": null,
        "voice": null,
        "net_price": 3.6,
        "created_at": "2025-11-18 13:37:07",
        "manual_installation": "<p><b>eSIM name:</b> Change</p><p><b>Coverage: </b>United States</p><p><b>To manually activate the eSIM on your eSIM capable device:</b></p><ol><li>Settings > Cellular/Mobile > Add Cellular/Mobile Plan.</li><li>Manually enter the SM-DP+ Address and activation code.</li><li>Confirm eSIM plan details.</li><li>Label the eSIM.</li></ol><p><b>To access Data:</b></p><ol><li>Enable data roaming.</li></ol>",
        "qrcode_installation": "<p><b>eSIM name:</b> Change</p><p><b>Coverage: </b>United States</p><p><b>To activate the eSIM by scanning the QR code on your eSIM capable device you need to print or display this QR code on other device:</b></p><ol><li>Settings > Cellular/Mobile > Add Cellular/Mobile Plan.</li><li>Scan QR code.</li><li>Confirm eSIM plan details.</li><li>Label the eSIM.</li></ol><p><b>To access Data:</b></p><ol><li>Enable data roaming.</li></ol>",
        "installation_guides": {
            "en": "https://www.airalo.com/help/getting-started-with-airalo"
        }
    },
    "meta": {
        "message": "success"
    }
}

🟠422Submit Top-up Order: 422 (Purchase limit exceeded)

🟠422Submit Top-up Order: 422 (Required fields are missing)

🟠422Submit Top-up Order: 422 (Invalid package id)

🟠422Submit Top-up Order: 422 (Recycled sim)

🟢200(Discount pricing) Submit Top-up Order