Skip to main content
GET
/
api
/
esim
/
packages
/
{packageCode}
Get Package Details
curl --request GET \
  --url https://api.vellosim.com/api/esim/packages/{packageCode} \
  --header 'X-API-Key: <api-key>'
{
  "packageCode": "US_5GB_30D",
  "name": "USA 5GB - 30 Days",
  "price": 5.75,
  "currencyCode": "USD",
  "volume": 5368709120,
  "duration": 30,
  "durationUnit": "DAY",
  "speed": "4G/5G",
  "description": "5GB data plan for the United States, valid for 30 days",
  "unusedValidTime": 30,
  "location": "United States",
  "locationCode": "US",
  "locationNetworkList": [
    {
      "locationName": "United States",
      "locationLogo": "https://example.com/flags/us.png",
      "locationCode": "US",
      "operatorList": [
        {
          "operatorName": "AT&T",
          "networkType": "4G/LTE"
        },
        {
          "operatorName": "T-Mobile",
          "networkType": "4G/5G"
        }
      ]
    }
  ]
}

​
Endpoint

GET /api/esim/packages/{packageCode}

​
Description

Returns detailed information for a single eSIM package, including pricing, data volume, duration, network coverage, and supported operators. Use this to display a package detail page or to confirm package info before purchase. Supports both BASE (new eSIM) and TOPUP (data refill) packages. To fetch a top-up package, either pass ?type=TOPUP or prefix the package code with TOPUP_ (e.g., TOPUP_CKH384). This is a public endpoint — authentication is optional. If an API key is provided, pricing will be calculated based on your account type (User or Merchant).

​
Authentication

​
X-API-Key
string
API Key for authentication. When provided, pricing reflects your account type.
YOUR_API_KEY

​
Path Parameters

​
packageCode
string
required
The unique package code identifier (e.g., US_5GB_30D).You can get package codes from the Get Packages endpoint.

​
Query Parameters

​
type
string
Package type:
  • BASE - New eSIM packages (default)
  • TOPUP - Top-up packages for existing eSIMs
If not provided, defaults to BASE. You can also prefix the packageCode with TOPUP_ instead of using this parameter.
​
currency
string
Override currency for pricing (e.g., NGN, USD, EUR).If not provided, defaults to USD.

​
Response

​
Success Response (200 OK)

​
packageCode
string
Unique package identifier
​
name
string
Package display name
​
price
number
Package price in USD (with markup applied)
​
currencyCode
string
Currency code (always USD)
​
volume
number
Data volume in bytes. Divide by 1073741824 (1024³) to convert to GB.
​
duration
number
Validity period (number of units)
​
durationUnit
string
Duration unit — DAY, HOUR, or MONTH
​
speed
string
Network speed (e.g., 3G/4G/5G)
​
description
string
Package description
​
locationNetworkList
array
List of covered locations and their network operators

​
Example Request

curl -X GET 'https://api.vellosim.com/api/esim/packages/US_5GB_30D' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Example Response

{
  "packageCode": "US_5GB_30D",
  "name": "USA 5GB - 30 Days",
  "price": 5.75,
  "currencyCode": "USD",
  "volume": 5368709120,
  "duration": 30,
  "durationUnit": "DAY",
  "speed": "4G/5G",
  "description": "5GB data plan for the United States, valid for 30 days",
  "unusedValidTime": 30,
  "location": "United States",
  "locationCode": "US",
  "locationNetworkList": [
    {
      "locationName": "United States",
      "locationLogo": "https://example.com/flags/us.png",
      "locationCode": "US",
      "operatorList": [
        {
          "operatorName": "AT&T",
          "networkType": "4G/LTE"
        },
        {
          "operatorName": "T-Mobile",
          "networkType": "4G/5G"
        }
      ]
    }
  ]
}

​
Converting Data Volume

Package volume is returned in bytes. Use these conversions: 
function formatDataVolume(bytes) {
  const gb = bytes / (1024 * 1024 * 1024);
  if (gb >= 1) return `${gb.toFixed(gb % 1 === 0 ? 0 : 1)}GB`;
  const mb = bytes / (1024 * 1024);
  return `${mb.toFixed(mb % 1 === 0 ? 0 : 1)}MB`;
}

// formatDataVolume(5368709120) → "5GB"
// formatDataVolume(536870912)  → "512MB"

​
Use Cases

Show full details before a user commits to purchase:
const pkg = await getPackageDetails('US_5GB_30D');

// Display to user
document.querySelector('.pkg-name').textContent = pkg.name;
document.querySelector('.pkg-price').textContent = `$${pkg.price}`;
document.querySelector('.pkg-data').textContent = formatDataVolume(pkg.volume);
document.querySelector('.pkg-duration').textContent = `${pkg.duration} days`;
document.querySelector('.pkg-speed').textContent = pkg.speed;
Verify package details and show NGN equivalent before buying:
const [pkg, rate] = await Promise.all([
  getPackageDetails(packageCode),
  getExchangeRate()
]);

const ngnPrice = Math.round(pkg.price * rate.rate * 100) / 100;
console.log(`${pkg.name}: $${pkg.price} (≈ ₦${ngnPrice.toLocaleString()})`);
Look up a top-up package using the type query parameter or TOPUP_ prefix:
// Option 1: Use type query parameter (recommended)
const topup = await getPackageDetails('CKH384', 'TOPUP');
console.log(`Top-up: ${topup.name} — $${topup.price}`);

// Option 2: Use TOPUP_ prefix
const topup2 = await getPackageDetails('TOPUP_CKH384');
console.log(`Top-up: ${topup2.name} — $${topup2.price}`);

​
Next Steps

Get All Packages

Browse all packages for a region

Top-Up Packages

Get available top-up packages for an existing eSIM

Purchase eSIM

Buy this package

Exchange Rate

Get USD → NGN rate for price conversion