eSIM

Order Creation

Kindly note that currently each eSIM prebooking order allows only one data package.

For lifestyle-related services, such as Fitness and eSIM, each resource (e.g., a specific fitness club or an eSIM for a certain region) may offer multiple options (e.g., different fitness classes or data plans). Orders are created at the option level within the corresponding resource.

The eSIM module supports two types of order creation:

1. Initial Order
Creates a new eSIM card (identified by a unique ICCID) and binds the selected data package to it. This option is used when the user does not have an existing eSIM.

2. Top-Up Order
Adds a new data package to an existing eSIM card. The ICCID of the existing card must be provided, and the selected data package will be applied to that card. This is used when the user wants to extend or renew the data service on a previously issued eSIM.

Initial Order

The prebooking flow typically includes the following steps:

Retrieve Option List

Retrieve the available options under a specific resource.

Availability Check

Query the availability of a specific option within a given resource for the specified date and time.

For most countries or regions, there is no restriction on the start time of the eSIM service. However, to ensure successful creation and issuance of the eSIM, it is recommended to set the prebooking time to at least one hour later (UTC+0).

Prebooking Creation

If available, a prebooking order can be created. The order remains cancellable within the applicable cancellation policy window.

Using the eSIM

Users can install the eSIM on their device in advance. Once they arrive at their destination and connect to a network, the eSIM will be activated automatically.

→ Use /orders/esims/ePasses/prebooking to place a eSIM prebooking order with an E-pass.

Request

Create E-pass Prebooking Order - eSIM - Request

For eSIM orders, no PII is required.

{
    "module": 8,
    "ePassId": "1788000066668888",
    "extra": {
        "prebookingToken": "85c69b8e790befc7e94870ec269c3f1d"
    }
}

Response

Create E-pass Prebooking Order - eSIM - Response

{
    "code": 0,
    "data": {
        "status": 1,
        "module": 8,
        "category": 2,
        "ePassId": "1788000066668888",
        "orderId": "DP00000000000001",
        "orderCreatedDate": "2024-12-31T00:00:00+00:00",
        "orderCancelledDate": null,
        "extra": {
            "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
            "prebookingDate": "2025-10-01T10:30",
            "usageDate": null,
            "usedUsages": 1,
            "resourceId": "E00001",
            "resourceName": "eSIM United Kingdom",
            "vouchersList": [
                {
                    "voucher": "668800008888",
                    "voucherType": 1
                }
            ],
            "esim": {
                "iccid": "898600F1234567890123",
                "status": 1,
                "effectiveDate": "2024-12-31T10:00:00+00:00",
                "expirationDate": "2025-12-31T10:00:00+00:00"
            },
            "esimOptions": {
                "optionId": "E00001-01",
                "optionName": "eSIM United Kingdom - 30GB 10Days",
                "status": 2,
                "duration": 10,
                "dataMode": 2,
                "volume": {
                    "total": 32212254720,
                    "remaining": 32212254720,
                    "dailyLimit": -1,
                    "notes": "Basic Unlimited Package provides 500MB of high-speed data, with unlimited usage at a reduced speed of 48 KB/s after high-speed data is used up. High-speed data refreshes every 24 hours."
                },
                "activationDate": null,
                "expirationDate": null,
                "speed": "5G",
                "providers": [
                    {
                        "provider": "DragonPass",
                        "region": "GB"
                    }
                ],
                "coverage": {
                    "type": 1,
                    "regions": [
                        "GB"
                    ],
                    "rawText": "United Kingdom"
                }
            },
            "esimOrderType": 1
        }
    }
}

Top-Up Order

The top-Up process follows these main steps:

Retrieve Option List

Retrieve the list of available options for a specific resource.

Top-up Availability Check

Verify whether a specific eSIM (identified by ICCID) supports top-up for a certain option(data package).

Due to carrier restrictions, some eSIMs only support specific data packages or do not support top-up.

Top-up

If available, a Top-up order can be created. The order remains cancellable within the applicable cancellation policy window.

Using the eSIM

Users can install the eSIM on their device in advance. Once they arrive at their destination and connect to a network, the eSIM will be activated automatically.

→ Use /orders/esims/ePasses/topup to place a eSIM top-up order with an E-pass.

Request

Top up eSIM data package - eSIM - Request

For eSIM orders, no PII is required.

{
    "module": 8,
    "ePassId": "1788000066668888",
    "extra": {
        "prebookingToken": "85c69b8e790befc7e94870ec269c3f1d",
        "iccid": "898600F1234567890123"
    }
}

Response

Top up eSIM data package - E-pass - eSIM - Response

{
    "code": 0,
    "data": {
        "status": 1,
        "module": 8,
        "category": 2,
        "ePassId": "1788000066668888",
        "orderId": "DP00000000000001",
        "orderCreatedDate": "2024-12-31T00:00:00+00:00",
        "orderCancelledDate": null,
        "extra": {
            "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
            "prebookingDate": "2025-10-01T10:30",
            "usageDate": null,
            "usedUsages": 1,
            "resourceId": "E00001",
            "resourceName": "eSIM United Kingdom",
            "vouchersList": [
                {
                    "voucher": "668800008888",
                    "voucherType": 1
                }
            ],
            "esim": {
                "iccid": "898600F1234567890123",
                "status": 1,
                "effectiveDate": "2024-12-31T10:00:00+00:00",
                "expirationDate": "2025-12-31T10:00:00+00:00"
            },
            "esimOptions": {
                "optionId": "E00001-01",
                "optionName": "eSIM United Kingdom - 30GB 10Days",
                "status": 2,
                "duration": 10,
                "dataMode": 2,
                "volume": {
                    "total": 32212254720,
                    "remaining": 32212254720,
                    "dailyLimit": -1,
                    "notes": "Basic Unlimited Package provides 500MB of high-speed data, with unlimited usage at a reduced speed of 48 KB/s after high-speed data is used up. High-speed data refreshes every 24 hours."
                },
                "activationDate": null,
                "expirationDate": null,
                "speed": "5G",
                "providers": [
                    {
                        "provider": "DragonPass",
                        "region": "GB"
                    }
                ],
                "coverage": {
                    "type": 1,
                    "regions": [
                        "GB"
                    ],
                    "rawText": "United Kingdom"
                }
            },
            "esimOrderType": 2
        }
    }
}

Cancel Orders

→ Use the /orders endpoint to cancel a prebooking order by order ID.

A prebooking order can be cancelled in accordance with the cancellation policy. Once cancelled, the corresponding usages will be refunded to the E-pass.

eSIM orders can be cancelled within 50 days of creation, provided that the data package has not been activated. Once the data package is activated, cancellation is no longer allowed.

Please note that once a prebooking order is cancelled, it cannot be recovered.

Retrieve eSIM Order Live Extended Details

→ Use the /orders/esims/details endpoint to retrieve real-time extended details of a specific eSIM order, covering usage, validity, and other supplementary information.

Request

Retrieve eSIM Order Extended Details - Request

{
    "orderId": "DP00000000000001"
}

Response

Retrieve eSIM Order Extended Details - Response

{
    "code": 0,
    "data": {
        "orderId": "DP00000000000001",
        "esim": {
            "iccid": "898600F1234567890123",
            "status": 1,
            "effectiveDate": "2024-12-31T10:00:00+00:00",
            "expirationDate": "2025-12-31T10:00:00+00:00"
        },
        "esimOptions": {
            "optionId": "E00001-01",
            "optionName": "eSIM United Kingdom - 30GB 10Days",
            "status": 2,
            "duration": 10,
            "dataMode": 2,
            "volume": {
                "total": 32212254720,
                "remaining": 32212254720,
                "notes": "Basic Unlimited Package provides 500MB of high-speed data, with unlimited usage at a reduced speed of 48 KB/s after high-speed data is used up. High-speed data refreshes every 24 hours."
            },
            "activationDate": "2025-10-15T10:00:00+00:00",
            "expirationDate": "2025-10-25T10:00:00+00:00",
            "speed": "5G",
            "providers": [
                {
                    "provider": "DragonPass",
                    "region": "GB"
                }
            ],
            "coverage": {
                "type": 1,
                "regions": [
                    "GB"
                ],
                "rawText": "United Kingdom"
            }
        }
    }
}

Retrieve eSIM Data Packages

→ Use the /orders/esims/packages/query endpoint to retrieve available data packages for a specific eSIM by supplying the ICCID along with either a membershipId or an ePassId.

Request

Retrieve eSIM Data Packages - Request

{
    "iccid": "898600F1234567890123",
    "ePassId": "1788000066668888"
}

Response

Retrieve eSIM Data Packages - Response

{
    "code": 0,
    "data": {
        "iccid": "898600F1234567890123",
        "packages": [
            {
                "orderId": "DP00000000000001",
                "optionId": "E00001-01",
                "optionName": "eSIM United Kingdom - 30GB 10Days",
                "status": 3,
                "duration": 10,
                "dataMode": 2,
                "activationDate": "2025-10-15T10:00:00+00:00",
                "expirationDate": "2025-10-25T10:00:00+00:00"
            },
            {
                "orderId": "DP00000000000002",
                "optionId": "E00001-02",
                "optionName": "eSIM United Kingdom - 10GB 10Days",
                "status": 2,
                "duration": 10,
                "dataMode": 2,
                "activationDate": null,
                "expirationDate": null
            }
        ]
    }
}

Order Creation#

Initial Order#

Top-Up Order#

Cancel Orders#

Retrieve eSIM Order Live Extended Details#

Retrieve eSIM Data Packages#

Order Creation

Initial Order

Top-Up Order

Cancel Orders

Retrieve eSIM Order Live Extended Details

Retrieve eSIM Data Packages