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