Get packages

Retrieve a list of local and global eSIM packages available through the Airalo Partners API. Local packages cover a single country, while global packages span multiple countries and regions. This endpoint helps you synchronize eSIM plans/packages with your system, ensuring newly introduced packages are available to your clients and out-of-stock packages are handled properly.

Features

Package Types: Supports standard data packages and the new "Voice and Text" packages.

Filtering: Filter results by operator type or country code to tailor the package list to your needs.

Pagination: Adjust pagination settings to retrieve results in manageable chunks.

Limit: Set the limit parameter to a high value (e.g., 1,000) to fetch all packages in a single request without using pagination.

Include Top-Up: Use the include:top-up parameter to fetch eSIM packages along with their associated top-up packages.

Multi-Currency

This endpoint provides pricing information in multiple currencies for both net prices and recommended retail prices. All currency conversion rates are updated once daily at 00:00 UTC.

Step-by-step implementation:

To keep your catalog up to date, including stock availability, new packages, and pricing, while avoiding performance or rate-limit issues, it’s important to run an hourly backend sync.
Below, we provide a step-by-step guide to help you successfully sync your packages:

Hourly Sync

Set up a background job via cron, worker, or cloud scheduler that calls GET /v2/packages once every hour.

Include the required authentication header: Authorization: Bearer <ACCESS_TOKEN> (Refer to Request access token)

Single Full Fetch (No Limit Param)

Call the endpoint without a limit parameter to retrieve the full catalogue (~3,200 packages) in a single response. This eliminates pagination and keeps the sync logic straightforward.

Alternatively, you can implement pagination or split sync runs (e.g. alternating between eSIMs and top-ups).

Rate-Limit Context

The API allows up to 40 requests per minute. One request per hour is far below this threshold and safe to run continuously.

Snapshot-Based Processing

Store the returned JSON as a complete snapshot (file, object storage, or database).

Upsert packages using package_id as the unique key.

Remove any packages missing from the latest snapshot.

Sync operators, coverage, pricing, and metadata fields.

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200List Packages (200)

application/json

Body

Example

{
    "pricing": {
        "model": "net_pricing",
        "discount_percentage": 0
    },
    "data": [
        {
            "slug": "united-states",
            "country_code": "US",
            "title": "United States",
            "image": {
                "width": 132,
                "height": 99,
                "url": "https://cdn.airalo.com/images/600de234-ec12-4e1f-b793-c70860e4545a.png"
            },
            "operators": [
                {
                    "id": 687,
                    "style": "light",
                    "gradient_start": "#0f1b3f",
                    "gradient_end": "#194281",
                    "type": "local",
                    "is_prepaid": false,
                    "title": "Change",
                    "esim_type": "Prepaid",
                    "warning": null,
                    "apn_type": "manual",
                    "apn_value": "wbdata",
                    "is_roaming": true,
                    "info": [
                        "5G Data-only eSIM.",
                        "Rechargeable online with no expiry.",
                        "Operates on T-Mobile and Verizon networks in the United States of America."
                    ],
                    "image": {
                        "width": 1035,
                        "height": 653,
                        "url": "https://cdn.airalo.com/images/030f0576-f611-4eee-bba5-eb90a994c4ff.png"
                    },
                    "plan_type": "data",
                    "activation_policy": "first-usage",
                    "is_kyc_verify": false,
                    "rechargeability": true,
                    "other_info": "This eSIM is for travelers to the United States. The coverage applies to all 50 states of the United States, and Puerto Rico.",
                    "coverages": [
                        {
                            "name": "US",
                            "code": "US",
                            "networks": [
                                {
                                    "name": "T-Mobile",
                                    "types": [
                                        "5G"
                                    ]
                                },
                                {
                                    "name": "Verizon",
                                    "types": [
                                        "5G"
                                    ]
                                }
                            ]
                        }
                    ],
                    "install_window_days": null,
                    "topup_grace_window_days": null,
                    "apn": {
                        "ios": {
                            "apn_type": "automatic",
                            "apn_value": "wbdata"
                        },
                        "android": {
                            "apn_type": "manual",
                            "apn_value": "wbdata"
                        }
                    },
                    "packages": [
                        {
                            "id": "change-7days-1gb",
                            "type": "sim",
                            "price": 4.5,
                            "amount": 1024,
                            "day": 7,
                            "is_unlimited": false,
                            "title": "1 GB - 7 Days",
                            "short_info": "This eSIM doesn't come with a phone number.",
                            "qr_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><p><b>To top up:</b></p><p>Visit airalo.com/my-esims or if purchased through the Airalo website/app visit “My eSIMs” tab.</p><p><br></p><p><br></p><p><br></p><p><br></p><p><br></p><p><br></p><p><br></p>",
                            "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><p><b>To top up:</b></p><p>Visit airalo.com/my-esims or if purchased through the Airalo website/app visit “My eSIMs” tab.</p><p><br></p><p><br></p><p><br></p><p><br></p><p><br></p><p><br></p><p><br></p>",
                            "is_fair_usage_policy": false,
                            "fair_usage_policy": null,

🟢200List Packages with topup (200)

🟢200List Global Packages (200)

🟢200List Local Packages (200)

🟢200List Local Packages for Specific Country (200)

🟢200List Packages with Pagination (200)

🟢200List Packages with Pagination page>=2 (200)

🟢200(Discount pricing) List Packages

🟠422List Packages (422)

Features#

Multi-Currency#

Step-by-step implementation:#

Hourly Sync#

Single Full Fetch (No Limit Param)#

Rate-Limit Context#

Snapshot-Based Processing#

Request