Skip to main content
GET
/
api
/
esim
/
packages?type=TOPUP
Get Top-Up Packages
curl --request GET \
  --url 'https://api.vellosim.com/api/esim/packages?type=TOPUP' \
  --header 'X-API-Key: <api-key>'
[
  {
    "packageCode": "CKH384_TOPUP_1GB",
    "name": "USA Top-Up 1GB - 7 Days",
    "price": 3.45,
    "currencyCode": "USD",
    "volume": 1073741824,
    "duration": 7,
    "durationUnit": "DAY",
    "speed": "4G/5G",
    "description": "1GB data top-up for existing USA eSIM",
    "locationNetworkList": [
      {
        "locationName": "United States",
        "locationCode": "US",
        "operatorList": [
          { "operatorName": "AT&T", "networkType": "4G/LTE" },
          { "operatorName": "T-Mobile", "networkType": "4G/5G" }
        ]
      }
    ]
  },
  {
    "packageCode": "CKH384_TOPUP_3GB",
    "name": "USA Top-Up 3GB - 30 Days",
    "price": 6.90,
    "currencyCode": "USD",
    "volume": 3221225472,
    "duration": 30,
    "durationUnit": "DAY",
    "speed": "4G/5G",
    "description": "3GB data top-up for existing USA eSIM",
    "locationNetworkList": [
      {
        "locationName": "United States",
        "locationCode": "US",
        "operatorList": [
          { "operatorName": "AT&T", "networkType": "4G/LTE" },
          { "operatorName": "T-Mobile", "networkType": "4G/5G" }
        ]
      }
    ]
  }
]

Endpoint

GET /api/esim/packages?type=TOPUP&regionCode={regionCode}&packageCode={packageCode}

Description

Returns available top-up (data refill) packages for an existing eSIM. Top-up packages let you add more data to an active eSIM without creating a new one. You need to provide the region code and the original package code of the eSIM you want to top up.

Authentication

X-API-Key
string
required
API Key for authentication
YOUR_API_KEY

Query Parameters

type
string
required
Must be TOPUP to fetch top-up packages.
regionCode
string
required
Region code of the existing eSIM (e.g., US, GB, EU).
packageCode
string
required
The original package code of the eSIM to top up (e.g., CKH384).You can get this from the eSIM order details (GET /api/esim/my-esims or GET /api/esim/:id).

Response

Returns an array of top-up packages with pricing.
packageCode
string
Top-up package identifier. Use this code when purchasing the top-up.
name
string
Top-up package display name
price
number
Price in USD (with markup applied)
currencyCode
string
Currency code (always USD)
volume
number
Additional data volume in bytes. Divide by 1073741824 to get GB.
duration
number
Additional validity period (number of units)
durationUnit
string
Duration unit — DAY, HOUR, or MONTH
speed
string
Network speed (e.g., 3G/4G/5G)

Example Request

curl -X GET 'https://api.vellosim.com/api/esim/packages?type=TOPUP&regionCode=US&packageCode=CKH384' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

[
  {
    "packageCode": "CKH384_TOPUP_1GB",
    "name": "USA Top-Up 1GB - 7 Days",
    "price": 3.45,
    "currencyCode": "USD",
    "volume": 1073741824,
    "duration": 7,
    "durationUnit": "DAY",
    "speed": "4G/5G",
    "description": "1GB data top-up for existing USA eSIM",
    "locationNetworkList": [
      {
        "locationName": "United States",
        "locationCode": "US",
        "operatorList": [
          { "operatorName": "AT&T", "networkType": "4G/LTE" },
          { "operatorName": "T-Mobile", "networkType": "4G/5G" }
        ]
      }
    ]
  },
  {
    "packageCode": "CKH384_TOPUP_3GB",
    "name": "USA Top-Up 3GB - 30 Days",
    "price": 6.90,
    "currencyCode": "USD",
    "volume": 3221225472,
    "duration": 30,
    "durationUnit": "DAY",
    "speed": "4G/5G",
    "description": "3GB data top-up for existing USA eSIM",
    "locationNetworkList": [
      {
        "locationName": "United States",
        "locationCode": "US",
        "operatorList": [
          { "operatorName": "AT&T", "networkType": "4G/LTE" },
          { "operatorName": "T-Mobile", "networkType": "4G/5G" }
        ]
      }
    ]
  }
]
Not all eSIM packages support top-ups. If no top-up packages are returned, the eSIM does not support data refills.

Next Steps

Top-Up eSIM

Apply a top-up to your eSIM

My eSIMs

Get your existing eSIMs

Exchange Rate

Get USD → NGN rate

Integration Guide

Full top-up integration guide