Skip to main content
GET
/
api
/
esim
/
packages
[
  {
    "packageCode": "US_5GB_30D",
    "packageName": "USA 5GB - 30 Days",
    "data": "5GB",
    "validity": 30,
    "price": 8000,
    "currency": "NGN",
    "originalPriceUSD": 10,
    "coverage": ["United States"],
    "networkProviders": ["AT&T", "T-Mobile", "Verizon"],
    "dataType": "Data Only",
    "speed": "4G/5G",
    "activation": "Automatic upon installation",
    "topUpAvailable": true
  },
  {
    "packageCode": "US_10GB_30D",
    "packageName": "USA 10GB - 30 Days",
    "data": "10GB",
    "validity": 30,
    "price": 15000,
    "currency": "NGN",
    "originalPriceUSD": 18,
    "coverage": ["United States"],
    "networkProviders": ["AT&T", "T-Mobile", "Verizon"],
    "dataType": "Data Only",
    "speed": "4G/5G",
    "activation": "Automatic upon installation",
    "topUpAvailable": true
  },
  {
    "packageCode": "US_UNLIMITED_30D",
    "packageName": "USA Unlimited - 30 Days",
    "data": "Unlimited",
    "validity": 30,
    "price": 25000,
    "currency": "NGN",
    "originalPriceUSD": 30,
    "coverage": ["United States"],
    "networkProviders": ["AT&T", "T-Mobile"],
    "dataType": "Data Only",
    "speed": "4G/5G (throttled after 50GB)",
    "activation": "Automatic upon installation",
    "topUpAvailable": false
  }
]

​
Endpoint

GET /api/esim/packages

​
Description

This endpoint returns eSIM packages available for a specific region. Prices are automatically calculated based on your account currency (NGN or USD).

​
Authentication

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

​
Query Parameters

​
regionCode
string
required
Region code to filter packages (e.g., “US”, “EU”, “ASIA”)Get available region codes from /api/esim/regions
​
type
string
Package type filter:
  • BASE - New eSIM packages (default)
  • TOPUP - Top-up packages for existing eSIMs
​
regionType
string
Filter by region type:
  • LC - Local (single country)
  • RG - Regional (multi-country)
  • GL - Global
​
packageCode
string
Specific package code to retrieve (required when type is TOPUP)

​
Response

​
packages
array
Array of package objects with pricing

​
Example Request

# Get packages for United States
curl -X GET 'https://api.vellosim.com/api/esim/packages?regionCode=US&type=BASE' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Get top-up packages for a specific eSIM
curl -X GET 'https://api.vellosim.com/api/esim/packages?regionCode=US&type=TOPUP&packageCode=US_5GB_30D' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Example Response

[
  {
    "packageCode": "US_5GB_30D",
    "packageName": "USA 5GB - 30 Days",
    "data": "5GB",
    "validity": 30,
    "price": 8000,
    "currency": "NGN",
    "originalPriceUSD": 10,
    "coverage": ["United States"],
    "networkProviders": ["AT&T", "T-Mobile", "Verizon"],
    "dataType": "Data Only",
    "speed": "4G/5G",
    "activation": "Automatic upon installation",
    "topUpAvailable": true
  },
  {
    "packageCode": "US_10GB_30D",
    "packageName": "USA 10GB - 30 Days",
    "data": "10GB",
    "validity": 30,
    "price": 15000,
    "currency": "NGN",
    "originalPriceUSD": 18,
    "coverage": ["United States"],
    "networkProviders": ["AT&T", "T-Mobile", "Verizon"],
    "dataType": "Data Only",
    "speed": "4G/5G",
    "activation": "Automatic upon installation",
    "topUpAvailable": true
  },
  {
    "packageCode": "US_UNLIMITED_30D",
    "packageName": "USA Unlimited - 30 Days",
    "data": "Unlimited",
    "validity": 30,
    "price": 25000,
    "currency": "NGN",
    "originalPriceUSD": 30,
    "coverage": ["United States"],
    "networkProviders": ["AT&T", "T-Mobile"],
    "dataType": "Data Only",
    "speed": "4G/5G (throttled after 50GB)",
    "activation": "Automatic upon installation",
    "topUpAvailable": false
  }
]

​
Package Types

TypeDescriptionUse Case
BASENew eSIM packagesFirst-time purchase for a region
TOPUPData top-up packagesAdd data to existing eSIM

​
Pricing

  • Prices are automatically converted to your account currency
  • NGN prices include the website’s price increment percentage
  • USD prices are shown for reference
  • All prices are final (no hidden fees)
Exchange rates and pricing increments are configured in your account settings

​
Use Cases

Show available packages in your UI:
async function displayPackages(regionCode) {
  const packages = await getPackages(regionCode);
  
  packages.forEach(pkg => {
    console.log(`${pkg.packageName}: ${pkg.currency} ${pkg.price}`);
    console.log(`Data: ${pkg.data}, Validity: ${pkg.validity} days`);
    console.log(`Networks: ${pkg.networkProviders.join(', ')}\n`);
  });
}
Let users filter packages by their budget:
function filterByPrice(packages, minPrice, maxPrice) {
  return packages.filter(pkg => 
    pkg.price >= minPrice && pkg.price <= maxPrice
  );
}

const affordablePackages = filterByPrice(packages, 0, 10000);
Display data top-up options for existing eSIMs:
async function getTopUpOptions(esimPackageCode) {
  const topups = await fetch(
    `/api/esim/packages?regionCode=US&type=TOPUP&packageCode=${esimPackageCode}`,
    { headers: { 'X-API-Key': ' YOUR_API_KEY' } }
  ).then(r => r.json());
  
  return topups;
}

​
Next Steps

Purchase eSIM

Buy an eSIM package

Get Package Details

Get detailed info for a specific package

Top Destinations

View popular destinations

Integration Guide

Build a package catalog UI