> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vellosim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Package Details

> Get detailed information for a specific eSIM package

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

<ParamField header="X-API-Key" type="string" optional>
  API Key for authentication. When provided, pricing reflects your account type.

  ```
  YOUR_API_KEY
  ```
</ParamField>

## Path Parameters

<ParamField path="packageCode" type="string" required>
  The unique package code identifier (e.g., `US_5GB_30D`).

  You can get package codes from the [Get Packages](/api-reference/esim/packages) endpoint.
</ParamField>

## Query Parameters

<ParamField query="type" type="string" optional>
  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.
</ParamField>

<ParamField query="currency" type="string" optional>
  Override currency for pricing (e.g., `NGN`, `USD`, `EUR`).

  If not provided, defaults to USD.
</ParamField>

## Response

### Success Response (200 OK)

<ResponseField name="packageCode" type="string">
  Unique package identifier
</ResponseField>

<ResponseField name="name" type="string">
  Package display name
</ResponseField>

<ResponseField name="price" type="number">
  Package price in USD (with markup applied)
</ResponseField>

<ResponseField name="currencyCode" type="string">
  Currency code (always `USD`)
</ResponseField>

<ResponseField name="volume" type="number">
  Data volume in bytes. Divide by `1073741824` (1024³) to convert to GB.
</ResponseField>

<ResponseField name="duration" type="number">
  Validity period (number of units)
</ResponseField>

<ResponseField name="durationUnit" type="string">
  Duration unit — `DAY`, `HOUR`, or `MONTH`
</ResponseField>

<ResponseField name="speed" type="string">
  Network speed (e.g., `3G/4G/5G`)
</ResponseField>

<ResponseField name="description" type="string">
  Package description
</ResponseField>

<ResponseField name="locationNetworkList" type="array">
  List of covered locations and their network operators

  <Expandable title="LocationNetwork Object">
    <ResponseField name="locationName" type="string">
      Country or region name
    </ResponseField>

    <ResponseField name="locationLogo" type="string">
      URL to location flag/logo
    </ResponseField>

    <ResponseField name="locationCode" type="string">
      Location code (e.g., `US`, `GB`)
    </ResponseField>

    <ResponseField name="operatorList" type="array">
      Available network operators

      <Expandable title="Operator Object">
        <ResponseField name="operatorName" type="string">
          Operator name (e.g., `AT&T`, `T-Mobile`)
        </ResponseField>

        <ResponseField name="networkType" type="string">
          Network type (e.g., `4G/LTE`)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL (BASE package) theme={null}
  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"
  ```

  ```bash cURL (TOPUP package) theme={null}
  # 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"
  ```

  ```javascript JavaScript theme={null}
  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}`);
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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";
  ?>
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "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"
          }
        ]
      }
    ]
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "success": false,
    "message": "Package not found",
    "statusCode": 404
  }
  ```
</ResponseExample>

## Converting Data Volume

Package `volume` is returned in **bytes**. Use these conversions:

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="Package Detail Page">
    Show full details before a user commits to purchase:

    ```javascript theme={null}
    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;
    ```
  </Accordion>

  <Accordion title="Pre-Purchase Confirmation">
    Verify package details and show NGN equivalent before buying:

    ```javascript theme={null}
    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()})`);
    ```
  </Accordion>

  <Accordion title="Top-Up Package Lookup">
    Look up a top-up package using the `type` query parameter or `TOPUP_` prefix:

    ```javascript theme={null}
    // 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}`);
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Get All Packages" icon="list" href="/api-reference/esim/packages">
    Browse all packages for a region
  </Card>

  <Card title="Top-Up Packages" icon="arrow-rotate-right" href="/api-reference/esim/topup-packages">
    Get available top-up packages for an existing eSIM
  </Card>

  <Card title="Purchase eSIM" icon="shopping-cart" href="/api-reference/purchase/buy">
    Buy this package
  </Card>

  <Card title="Exchange Rate" icon="dollar-sign" href="/api-reference/settings/exchange-rate">
    Get USD → NGN rate for price conversion
  </Card>
</CardGroup>