Get Package Details

curl --request GET \
  --url https://api.vellosim.com/api/esim/packages/{packageCode} \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.vellosim.com/api/esim/packages/{packageCode}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vellosim.com/api/esim/packages/{packageCode}",
  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/{packageCode}"

	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": "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"
        }
      ]
    }
  ]
}

{
  "success": false,
  "message": "Package not found",
  "statusCode": 404
}

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>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.vellosim.com/api/esim/packages/{packageCode}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vellosim.com/api/esim/packages/{packageCode}",
  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/{packageCode}"

	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": "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"
        }
      ]
    }
  ]
}

{
  "success": false,
  "message": "Package not found",
  "statusCode": 404
}

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

string

API Key for authentication. When provided, pricing reflects your account type.

YOUR_API_KEY

Path Parameters

string

required

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

Query Parameters

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.

string

Override currency for pricing (e.g., NGN, USD, EUR).If not provided, defaults to USD.

Response

Success Response (200 OK)

string

Unique package identifier

string

Package display name

number

Package price in USD (with markup applied)

string

Currency code (always USD)

number

Data volume in bytes. Divide by 1073741824 (1024³) to convert to GB.

number

Validity period (number of units)

string

Duration unit — DAY, HOUR, or MONTH

string

Network speed (e.g., 3G/4G/5G)

string

Package description

array

List of covered locations and their network operators

Show LocationNetwork Object

string

Country or region name

string

URL to location flag/logo

string

Location code (e.g., US, GB)

array

Available network operators

Show Operator Object

string

Operator name (e.g., AT&T, T-Mobile)

string

Network type (e.g., 4G/LTE)

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"

# Option 1: Use type query parameter
curl -X GET 'https://api.vellosim.com/api/esim/packages/CKH384?type=TOPUP' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Option 2: Use TOPUP_ prefix
curl -X GET 'https://api.vellosim.com/api/esim/packages/TOPUP_CKH384' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

async function getPackageDetails(packageCode, type = 'BASE') {
  const params = new URLSearchParams();
  if (type !== 'BASE') params.set('type', type);

  const url = `https://api.vellosim.com/api/esim/packages/${packageCode}${params.toString() ? '?' + params : ''}`;

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });

  return await response.json();
}

// Get a BASE package
const details = await getPackageDetails('US_5GB_30D');
console.log(`${details.name} — $${details.price}`);

// Get a TOPUP package
const topup = await getPackageDetails('CKH384', 'TOPUP');
console.log(`Top-up: ${topup.name} — $${topup.price}`);

import requests

def get_package_details(package_code, pkg_type='BASE'):
    """Get details for a specific eSIM package"""
    headers = {
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    }

    params = {}
    if pkg_type != 'BASE':
        params['type'] = pkg_type

    response = requests.get(
        f'https://api.vellosim.com/api/esim/packages/{package_code}',
        headers=headers,
        params=params
    )

    return response.json()

# Get a BASE package
details = get_package_details('US_5GB_30D')
data_gb = details['volume'] / (1024 ** 3)
print(f"{details['name']} — ${details['price']}")

# Get a TOPUP package
topup = get_package_details('CKH384', 'TOPUP')
print(f"Top-up: {topup['name']} — ${topup['price']}")

<?php
function getPackageDetails($packageCode, $type = 'BASE') {
    $apiKey = 'YOUR_API_KEY';

    $query = $type !== 'BASE' ? '?' . http_build_query(['type' => $type]) : '';

    $ch = curl_init("https://api.vellosim.com/api/esim/packages/{$packageCode}{$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;
}

// Get a BASE package
$details = getPackageDetails('US_5GB_30D');
echo "{$details['name']} — \${$details['price']}\n";

// Get a TOPUP package
$topup = getPackageDetails('CKH384', 'TOPUP');
echo "Top-up: {$topup['name']} — \${$topup['price']}\n";
?>

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"
        }
      ]
    }
  ]
}

{
  "success": false,
  "message": "Package not found",
  "statusCode": 404
}

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

Package Detail Page

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;

Pre-Purchase Confirmation

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()})`);

Top-Up Package Lookup

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

Overview

Wallet

Settings

eSIM

Purchase

Orders

Get Package Details

Endpoint

Description

Authentication

Path Parameters

Query Parameters

Response

Success Response (200 OK)

Example Request

Example Response

Converting Data Volume

Use Cases

Next Steps

Get All Packages

Top-Up Packages

Purchase eSIM

Exchange Rate

​Endpoint

​Description

​Authentication

​Path Parameters

​Query Parameters

​Response

​Success Response (200 OK)

​Example Request

​Example Response

​Converting Data Volume

​Use Cases

​Next Steps

Get All Packages

Top-Up Packages

Purchase eSIM

Exchange Rate

Endpoint

Description

Authentication

Path Parameters

Query Parameters

Response

Success Response (200 OK)

Example Request

Example Response

Converting Data Volume

Use Cases

Next Steps