Skip to main content

​
Overview

After a user selects a region, fetch available eSIM packages with their pricing, data allowance, and validity period. Packages come in two types: BASE (new eSIM) and TOPUP (add data to existing eSIM).

​
Quick Start

async function getPackages(regionCode) {
  const response = await fetch(
    `https://api.vellosim.com/api/esim/packages?regionCode=${regionCode}&type=BASE`,
    {
      method: 'GET',
      headers: {
        'X-API-Key': `API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  const packages = await response.json();  // Direct array response
  return packages;
}

// Helper function to convert bytes to GB
function bytesToGB(bytes) {
  return (bytes / 1073741824).toFixed(2);
}

// Usage
const packages = await getPackages('US');
console.log(`Found ${packages.length} packages for United States`);
packages.forEach(pkg => {
  console.log(`${pkg.name}: ${bytesToGB(pkg.volume)}GB for ${pkg.duration} days`);
});

​
Response Format

The API returns a direct array of package objects: 
[
  {
    "packageCode": "CKH533",
    "name": "United States 1GB 7Days",
    "price": 2160,
    "currencyCode": "NGN",
    "duration": 7,
    "volume": 1073741824,
    "description": "United States 1GB 7Days",
    "unusedValidTime": 180,
    "durationUnit": "DAY",
    "location": "US",
    "locationCode": "US",
    "speed": "3G/4G/5G",
    "locationNetworkList": [
      {
        "locationName": "United States",
        "locationLogo": "https://flagcdn.com/w320/us.png",
        "locationCode": "US",
        "operatorList": [
          {
            "operatorName": "T-Mobile",
            "networkType": "5G"
          }
        ]
      }
    ]
  }
]
Important: The response is a direct array, not wrapped in an object with a packages key.

​
Response Fields

FieldTypeDescription
packageCodestringUnique identifier for the package
namestringDisplay name of the package
pricenumberPackage price (in minor units, e.g., kobo for NGN)
currencyCodestringCurrency code (e.g., “NGN”, “USD”)
durationnumberValidity period duration
durationUnitstringUnit of validity (“DAY”, “MONTH”, etc.)
volumenumberData allowance in bytes (e.g., 1073741824 = 1GB)
descriptionstringPackage description
unusedValidTimenumberDays package remains valid before activation
locationstringComma-separated list of country codes
locationCodestringPrimary region/location code
speedstringNetwork speed (e.g., “3G/4G/5G”)
locationNetworkListarrayList of covered locations with operators

​
Location Network Object

FieldTypeDescription
locationNamestringCountry/region name
locationLogostringFlag icon URL from flagcdn.com
locationCodestringISO country code
operatorListarrayAvailable mobile operators
Data Volume Conversion: The volume field is in bytes. Convert to GB: volume / 1073741824

​
Understanding Location Networks

Each package includes detailed information about supported locations and mobile operators: 
// Display supported countries and operators
function displayPackageNetworks(pkg) {
  console.log(`Package: ${pkg.name}`);
  console.log(`Coverage: ${pkg.locationNetworkList.length} location(s)\n`);
  
  pkg.locationNetworkList.forEach(location => {
    console.log(`📍 ${location.locationName} (${location.locationCode})`);
    console.log(`   Flag: ${location.locationLogo}`);
    console.log(`   Operators:`);
    
    location.operatorList.forEach(operator => {
      console.log(`   - ${operator.operatorName} (${operator.networkType})`);
    });
    console.log('');
  });
}

// Example: Multi-country package (Europe)
const europePackages = await getPackages('EU-42');
displayPackageNetworks(europePackages[0]);
// Output:
// Package: Europe 1GB 7Days
// Coverage: 42 location(s)
// 
// 📍 United Kingdom (GB)
//    Flag: https://flagcdn.com/w320/gb.png
//    Operators:
//    - Vodafone (5G)
//    - O2 (5G)
//    - 3 (5G)

​
Query Parameters

​
Required Parameters

  • regionCode (required): The region code to fetch packages for (e.g., “US”, “EU-42”)

​
Optional Parameters

  • type: Package type filter
    • BASE: New eSIM packages (default)
    • TOPUP: Top-up packages for existing eSIMs
  • regionType: Filter by region type
    • LC: Local (single country)
    • RG: Regional (multi-country)
    • GL: Global
  • packageCode: Specific package code (required when type=TOPUP)

​
Filter by Package Type

// Get BASE packages (new eSIM)
const basePackages = await fetch(
  'https://api.vellosim.com/api/esim/packages?regionCode=US&type=BASE',
  { headers: { 'X-API-Key': `API_KEY}` } }
).then(r => r.json());

// Get TOPUP packages (requires existing packageCode)
const topupPackages = await fetch(
  'https://api.vellosim.com/api/esim/packages?regionCode=US&type=TOPUP&packageCode=CKH533',
  { headers: { 'X-API-Key': `API_KEY}` } }
).then(r => r.json());

// Top-up packages have TOPUP_ prefix in packageCode
console.log(topupPackages[0].packageCode); // "TOPUP_P3ICIKSE8"
Top-Up Packages: When fetching top-up packages, you must provide the packageCode of the BASE package the user originally purchased. Top-up packages are filtered to only show compatible data add-ons for that eSIM.

​
Filter by Region Type

// Get regional (multi-country) packages for Europe
const regionalPackages = await fetch(
  'https://api.vellosim.com/api/esim/packages?regionCode=EU-42&type=BASE&regionType=RG',
  { headers: { 'X-API-Key': `API_KEY}` } }
).then(r => r.json());

​
Next Steps

Purchase eSIM

Complete the purchase with selected package

Get Top-Up Packages

Add data to existing eSIM