Get Top-Up Packages
curl --request GET \
--url 'https://api.vellosim.com/api/esim/packages?type=TOPUP' \
--header 'X-API-Key: <api-key>'const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.vellosim.com/api/esim/packages?type=TOPUP', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.vellosim.com/api/esim/packages?type=TOPUP"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vellosim.com/api/esim/packages?type=TOPUP",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.vellosim.com/api/esim/packages?type=TOPUP"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}[
{
"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" }
]
}
]
}
]
{
"success": false,
"message": "regionCode and packageCode are required for TOPUP type"
}
eSIM
Get Top-Up Packages
Get available data top-up packages for an existing eSIM
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>'const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.vellosim.com/api/esim/packages?type=TOPUP', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.vellosim.com/api/esim/packages?type=TOPUP"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vellosim.com/api/esim/packages?type=TOPUP",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.vellosim.com/api/esim/packages?type=TOPUP"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}[
{
"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" }
]
}
]
}
]
{
"success": false,
"message": "regionCode and packageCode are required for TOPUP type"
}
Endpoint
GET /api/esim/packages?type=TOPUP®ionCode={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
string
required
API Key for authentication
YOUR_API_KEY
Query Parameters
string
required
Must be
TOPUP to fetch top-up packages.string
required
Region code of the existing eSIM (e.g.,
US, GB, EU).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.string
Top-up package identifier. Use this code when purchasing the top-up.
string
Top-up package display name
number
Price in USD (with markup applied)
string
Currency code (always
USD)number
Additional data volume in bytes. Divide by
1073741824 to get GB.number
Additional validity period (number of units)
string
Duration unit —
DAY, HOUR, or MONTHstring
Network speed (e.g.,
3G/4G/5G)Example Request
curl -X GET 'https://api.vellosim.com/api/esim/packages?type=TOPUP®ionCode=US&packageCode=CKH384' \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
async function getTopUpPackages(regionCode, packageCode) {
const params = new URLSearchParams({
type: 'TOPUP',
regionCode,
packageCode
});
const response = await fetch(
`https://api.vellosim.com/api/esim/packages?${params}`,
{
method: 'GET',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
}
}
);
return await response.json();
}
// Usage — get top-up options for an existing US eSIM
const topups = await getTopUpPackages('US', 'CKH384');
console.log(`Found ${topups.length} top-up options`);
topups.forEach(pkg => {
const dataGB = (pkg.volume / 1073741824).toFixed(1);
console.log(`${pkg.name}: ${dataGB}GB — $${pkg.price} (${pkg.duration} ${pkg.durationUnit}s)`);
});
import requests
def get_topup_packages(region_code, package_code):
"""Get available top-up packages for an existing eSIM"""
headers = {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
}
params = {
'type': 'TOPUP',
'regionCode': region_code,
'packageCode': package_code
}
response = requests.get(
'https://api.vellosim.com/api/esim/packages',
headers=headers,
params=params
)
return response.json()
# Usage
topups = get_topup_packages('US', 'CKH384')
print(f"Found {len(topups)} top-up options")
for pkg in topups:
data_gb = pkg['volume'] / (1024 ** 3)
print(f"{pkg['name']}: {data_gb:.1f}GB — ${pkg['price']}")
<?php
function getTopUpPackages($regionCode, $packageCode) {
$apiKey = 'YOUR_API_KEY';
$query = http_build_query([
'type' => 'TOPUP',
'regionCode' => $regionCode,
'packageCode' => $packageCode
]);
$ch = curl_init("https://api.vellosim.com/api/esim/packages?{$query}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'X-API-Key: ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
return $data;
}
// Usage
$topups = getTopUpPackages('US', 'CKH384');
echo "Found " . count($topups) . " top-up options\n";
foreach ($topups as $pkg) {
$dataGB = $pkg['volume'] / (1024 ** 3);
echo "{$pkg['name']}: {$dataGB}GB — \${$pkg['price']}\n";
}
?>
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" }
]
}
]
}
]
{
"success": false,
"message": "regionCode and packageCode are required for TOPUP type"
}
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
⌘I
