---
title: Travel eSIM
description: Integrate Travel eSIM products for international data connectivity
---

Travel eSIM provides prepaid international data connectivity for travelers. This guide walks you through the Travel eSIM integration, from browsing available packages to provisioning and topups.

## Core concept

A Travel eSIM consists of two components:

- **Subscription**: The eSIM container that holds the SIM reference (ICC, MSISDN)
- **Data package (Addon)**: Contains the actual data allowance, validity period, and supported countries/regions

> **Note**
>
> A subscription always requires at least one data package to be usable. Topups are handled by
> adding additional packages to an existing subscription.

## Quick path

**1. Browse packages**

List available Travel eSIM data packages filtered by country or region.

**2. Create order**

Create an order with both the subscription and initial data package.

**3. Read price**

Read the taxes and totals off the order before payment.

**4. Collect payment**

Collect payment through your own provider or use a managed payment session.

**5. Submit order**

Submit the order to provision the eSIM and activate the data package.

## Order structure

When creating a Travel eSIM order, you need two line items:

1. **Subscription line item** (`TRAVEL_ESIM`): Creates the eSIM profile
2. **Addon line item** (`TRAVEL_ESIM_PACKAGE`): Activates the data package
```
Order
├── Line Item 1: Subscription (TRAVEL_ESIM)
│   └── Gets ICC, MSISDN from provisioning
│
└── Line Item 2: Addon (TRAVEL_ESIM_PACKAGE)
    ├── dataGb
    ├── validityDays
    ├── countries[] (ISO 3166-1 alpha-2: "ES", "FR")
    ├── regions[] (EUROPE, AMERICAS, ASIA_PACIFIC, GLOBAL)
    └── activationType (INSTANT, FIRST_USE)
```

> **Info**
>
> Use `parentLineItemId` to link the addon to a new subscription in the same order. Use
> `subscriptionId` when adding packages to an existing subscription.

## 1. Browse available packages

List Travel eSIM data packages available for purchase. You can filter by country or region to show relevant options to your customers.

```bash
# List all Travel eSIM addon packages
curl "{BASE_URL}/products/offerings?categories=TRAVEL_ESIM_PACKAGE" \
  -H "X-API-Key: $API_KEY"
```

### Filter by country

```bash
# List packages available in Spain
curl "{BASE_URL}/products/offerings?categories=TRAVEL_ESIM_PACKAGE&countries=ES" \
  -H "X-API-Key: $API_KEY"
```

### Filter by region

```bash
# List packages for Europe
curl "{BASE_URL}/products/offerings?categories=TRAVEL_ESIM_PACKAGE&regions=EUROPE" \
  -H "X-API-Key: $API_KEY"
```

Available regions: `EUROPE`, `AMERICAS`, `ASIA_PACIFIC`, `GLOBAL`

See [List Product Offerings](/api-reference/product-offerings.md#tag/product-offerings/GET/product-offerings)

## 2. Create order

Create an order with both the subscription (eSIM container) and the initial data package.

```bash
curl -X POST "{BASE_URL}/orders" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "customerId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "lineItems": [
      {
        "type": "SUBSCRIPTION",
        "lineItemId": "esim-container",
        "productOfferingId": "travel-esim-subscription-offering-id",
        "subscriber": {
          "name": "John Doe",
          "email": "john@example.com"
        },
        "sim": {
          "esim": true
        }
      },
      {
        "type": "ADDON",
        "lineItemId": "data-package",
        "productOfferingId": "europe-5gb-30days-offering-id",
        "parentLineItemId": "esim-container"
      }
    ]
  }'
```

> **Warning**
>
> Orders with a `TRAVEL_ESIM` subscription must include at least one `TRAVEL_ESIM_PACKAGE` line
> item. The order will be rejected if no data package is included.

See [Create Order](/api-reference/orders.md#tag/orders/POST/orders)

## 3. Read the order price

Taxes and totals are recalculated whenever the order changes, so read them off the order before collecting payment.

```bash
curl "{BASE_URL}/orders/{orderId}" \
  -H "X-API-Key: $API_KEY"
```

See [Get Order](/api-reference/orders.md#tag/orders/GET/orders/{orderId})

## 4. Collect payment

Travel eSIM orders require prepaid payment before submission. You can collect payment through your own payment provider or use a managed payment session.

### Option A: Your own payment provider (recommended)

Collect the payment through your own payment provider, such as Stripe, Adyen, or Braintree.
Then pass the payment reference when you submit the order. You keep full control of the
checkout, and you keep the payment infrastructure that you already run.

```bash
# Step 1: Collect payment through your own provider
# (This happens in your existing payment flow)

# Step 2: Submit the order with the payment reference
curl -X POST "{BASE_URL}/orders/{orderId}/submit" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalPayment": {
      "reference": "pi_3ABC123def456",
      "receiptDescription": "Travel eSIM data package",
      "receiptUrl": "https://yourapp.com/receipts/abc123"
    }
  }'
```

> **Note**
>
> When using external payments, you are responsible for collecting the correct amount and handling
> refunds through your payment provider.

### Option B: Payment session API

If you prefer a managed payment flow, use the Payment Session API to create a payment session. You can use a hosted checkout page or an embedded payment widget.

```bash
curl -X POST "{BASE_URL}/payment-sessions" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "{orderId}",
    "paymentProvider": "STRIPE",
    "hosted": true,
    "returnUrl": "https://yourapp.com/payment/success",
    "cancelUrl": "https://yourapp.com/payment/cancel"
  }'

# Redirect customer to provider.checkoutUrl from the response for payment
```

See [Create Payment Session](/api-reference/payment-sessions.md#tag/payment-sessions/POST/payment-sessions)

## 5. Submit order

Submit the order to provision the eSIM and activate the data package. If you used external payment (Option A), the order is already submitted from step 4. If you used a payment session (Option B), submit the order with the payment session ID.

```bash
curl -X POST "{BASE_URL}/orders/{orderId}/submit" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentSessionId": "{paymentSessionId}"
  }'

# The created subscription ID is in createdEntities.subscriptions in the response
```

See [Submit Order](/api-reference/orders.md#tag/orders/POST/orders/{orderId}/submit)

## 6. Retrieve eSIM QR code

After the order is submitted, retrieve the eSIM QR code for the customer to install on their device.

```bash
curl "{BASE_URL}/subscriptions/{subscriptionId}/esim/qrcode" \
  -H "X-API-Key: $API_KEY"

# Display the returned QR code to the customer for eSIM installation
```

See [Get eSIM QR Code](/api-reference/subscriptions.md#tag/subscriptions/GET/subscriptions/{subscriptionId}/esim/qrcode)

## Topup to add more data

When a customer needs more data, create a new order with an addon line item linked to the existing subscription.

```bash
curl -X POST "{BASE_URL}/orders" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "customerId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "lineItems": [
      {
        "type": "ADDON",
        "lineItemId": "topup-package",
        "productOfferingId": "europe-10gb-30days-offering-id",
        "subscriptionId": "{subscriptionId}"
      }
    ]
  }'

# Continue with reading the price, payment, and submit as above
```

> **Note**
>
> Multiple data packages can coexist on one subscription, even covering different regions. Each
> package has its own validity period and data allowance.

## Check usage

Monitor data consumption for a Travel eSIM subscription.

```bash
curl "{BASE_URL}/subscriptions/{subscriptionId}/usage" \
  -H "X-API-Key: $API_KEY"
```

See [Get Subscription Usage](/api-reference/subscription-usage.md#tag/subscription-usage/GET/subscriptions/{subscriptionId}/usage)

## Subscription states

| State       | Description                            |
| ----------- | -------------------------------------- |
| `PENDING`   | Order submitted, awaiting provisioning |
| `ACTIVE`    | eSIM provisioned and ready for use     |
| `CANCELLED` | Subscription terminated                |

> **Info**
>
> The subscription stays `ACTIVE` even when data packages expire. Customers can always add more
> packages to continue using the eSIM.

## Data package states

| State       | Description                          |
| ----------- | ------------------------------------ |
| `PENDING`   | Package ordered, awaiting activation |
| `ACTIVE`    | Package activated and data available |
| `EXPIRED`   | Validity period ended                |
| `CANCELLED` | Package canceled before expiration   |

## Activation types

Data packages support two activation types:

- **INSTANT**: Package activates immediately upon order submission
- **FIRST_USE**: Package activates when the customer first connects to the network

## Cancel subscription

To cancel a Travel eSIM subscription:

```bash
curl -X POST "{BASE_URL}/subscriptions/{subscriptionId}/cancel" \
  -H "X-API-Key: $API_KEY"
```

See [Cancel Subscription](/api-reference/subscriptions.md#tag/subscriptions/POST/subscriptions/{subscriptionId}/cancel)

## Next steps

- [Product offerings](/api-reference/product-offerings.md) — Browse and filter available Travel eSIM packages
- [Orders](/api-reference/orders.md) — Learn more about order management
- [Subscription usage](/api-reference/subscription-usage.md) — Monitor data consumption and usage patterns
- [Webhooks](/api-reference/webhooks.md) — Set up notifications for order and subscription events