eSIM Top Up with the API

In the latest API update, we pushed the top up functionality for both the API and console. In these videos Bryan explains how to find what data top ups are available for each eSIM and then how to subscribe to the package.

Perquisites

Before you get started, make sure you have a free Postman account, eSIM Access account and have funded your account with enough for a purchase, and have an active eSIM in your account.

Follow these steps to make a TOPUP request

Lets go thru the steps to make a TOPUP purchase.

1. First, verify you have an active eSIM profile in your account.
2. Locate the ICCID number of the eSIM you wish to top up
3. In the Package List endpoint send “type”:”TOPUP”, and “iccid”:”<your_iccid>”
4. Review the available package with the TOPUP_ prefix
5. With top up package code and ICCIC, go to the Top Up endpoint
6. A success response gives an updated validity and total data volume.

Setup steps in more detail

Verify that you have an active eSIM profile in your account: This is the initial step in topping up your eSIM. You’ll need to log into your account and check the status of your eSIM profiles. In order to make a top up purchase, your eSIM profile must be active.

Locate the ICCID number of the eSIM you wish to top up: ICCID stands for Integrated Circuit Card Identifier, which is a unique number that’s associated with your eSIM. This number is required to ensure that the top up is applied to the correct eSIM. This can be found in the Query Profile endpoint.

In the Package List endpoint, send “type”: “TOPUP”, and “iccid”: “<your_iccid>”: This step involves interfacing with the API. The Package List endpoint is a specific function within the API that allows you to view your package options. By sending a request to this endpoint with “type”: “TOPUP” and including your ICCID, you’re asking the API to give you information about top up packages available for your specific eSIM.

{
    "locationCode": "",
    "type":"TOPUP",
    "packageCode":"",
    "iccid":"89852245234001354019"
}

Review the available package with the TOPUP_ prefix: The packages returned from the previous API request will include different types of packages, including those for topping up your eSIM. These top up packages should be identifiable by the “TOPUP_” prefix. Take some time to review the details of these packages to decide which one best suits your needs.

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "packageList": [
            {
                "packageCode": "TOPUP_CKH491",
                "name": "North America 1GB 7Days",
                "price": 70000,
                "currencyCode": "USD",
                "volume": 1073741824,
                "unusedValidTime": 30,
                "duration": 7,
                "durationUnit": "DAY",
                "location": "US,CA",
                "description": "North America 1GB 7Days",
                "activeType": 1
            },
            {
                "packageCode": "TOPUP_CKH494",
                "name": "North America 10GB 30Days",
                "price": 595000,
                "currencyCode": "USD",
                "volume": 10737418240,
                "unusedValidTime": 30,
                "duration": 30,
                "durationUnit": "DAY",
                "location": "US,CA",
                "description": "North America 10GB 30Days",
                "activeType": 1
            },
            {
                "packageCode": "TOPUP_CKH535",
                "name": "North America 20GB 30Days",
                "price": 1160700,
                "currencyCode": "USD",
                "volume": 21474836480,
                "unusedValidTime": 30,
                "duration": 30,
                "durationUnit": "DAY",
                "location": "US,CA",
                "description": "North America 20GB 30Days",
                "activeType": 1
            },
            {
                "packageCode": "TOPUP_CKH536",
                "name": "North America 50GB 30Days",
                "price": 2901800,
                "currencyCode": "USD",
                "volume": 53687091200,
                "unusedValidTime": 30,
                "duration": 30,
                "durationUnit": "DAY",
                "location": "US,CA",
                "description": "North America 50GB 30Days",
                "activeType": 1
            }
        ]
    }
}

With the top-up package code and ICCID, go to the Top-Up endpoint: Once you’ve chosen a package, you’ll need to make another API request, this time to the Top-Up endpoint. This function is designed to apply a top-up package to your eSIM. In this request, you’ll include the code for the top-up package you’ve chosen, as well as your ICCID.

{
    "iccid":"89852245280001354019",
    "packageCode":"TOPUP_CKH491",
    "transactionId": "test_top_up_TOPUP_CKH491_05",
    "amount": 70000
}

A success response gives an updated validity and total data volume: If your top-up request is successful, the API will respond with confirmation. This response will include important information about your eSIM, such as its updated validity (i.e., how long before it needs to be topped up again) and total data volume (i.e., how much data you can use before your eSIM runs out). Keep track of this information to ensure you don’t run out of data unexpectedly.

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": {
        "transactionId": "fb9b22193f3c45aab4f052efbc878f30",
        "iccid": "89852245280001354019",
        "expiredTime": "2023-08-24T17:01:37+0000",
        "totalVolume": 5368709120,
        "totalDuration": 35,
        "orderUsage": 907415004
    }
}