Tavaro eSIM API

Add eSIM connectivity to your travel platform. Instant delivery, 200+ destinations, one simple API.

✓ REST API ✓ JSON ✓ 200+ Countries ✓ Instant QR Delivery v1.0 · Stable

Base URL

https://api.tavaroesim.com

Overview

The Tavaro API lets you embed eSIM purchasing directly into your platform. Your customers browse plans, pay through your checkout, and receive their eSIM instantly via QR code. All costs are deducted from your prepaid Tavaro Credits balance.

✓

No ops, no logisticseSIMs are fully digital. No physical SIM cards, no shipping, no activation delays. Your customer scans a QR code and is connected.

How It Works

1

Create a Partner Account

Sign up at tavaropartners.com and top up your Tavaro Credits.

2

Generate an API Key

Go to API Access in your partner portal. Your key starts with tvr_.

3

Browse & Display Plans

Call /v1/countries and /v1/packages to show eSIM plans in your platform.

4

Place Orders

Call /v1/order at checkout. Credits deducted instantly. eSIM returned in the response.

5

Deliver to Customer

Send the QR code, iOS install link, or LPA code. Customer installs in minutes.

Supported Use Cases

Use Case	How
B2C travel booking	Show eSIM at checkout alongside flights/hotels
B2B travel agents	Agents order on behalf of travellers via your platform
Mobile app	Integrate directly into iOS/Android travel app
OTA platform	Add as ancillary product in your booking flow

Common Pitfalls

These are the most common integration mistakes. Read this before you start — it will save you hours of debugging.

⚠

planId vs packageId — they are different fields When placing a new order via POST /v1/order, use planId from /v1/packages. When applying a top-up via POST /v1/esim/topup, use packageId from /v1/esim/topup/packages. These are separate identifiers for separate flows — do not mix them.

⚠

esimId vs iccid — save both from the order response The order response returns two identifiers for each eSIM. esimId is used to check eSIM status via GET /v1/esim/:esimId. iccid is used for top-up via GET /v1/esim/topup/packages and POST /v1/esim/topup. Store both in your database at order time — you cannot retrieve them later without contacting support.

⚠

Never call order or top-up endpoints from your frontend Your API key must stay secret. All calls to /v1/order, /v1/esim/topup, and any write endpoint must be made from your backend server only. A key exposed in client-side JavaScript will be visible to anyone who inspects your page source.

ℹ

Top-up is not available on all plans Only eSIMs purchased on plans where topUp: true in /v1/packages can be topped up. Always check the topUp field before showing a top-up option to your customers. If GET /v1/esim/topup/packages returns an empty array, that eSIM cannot be topped up.

Identifier Quick Reference

Identifier	Where it comes from	What it's used for
planId	`/v1/packages` response	Placing a new order — `POST /v1/order`
packageId	`/v1/esim/topup/packages` response	Applying a top-up — `POST /v1/esim/topup`
esimId	`/v1/order` response	Checking eSIM status — `GET /v1/esim/:esimId`
iccid	`/v1/order` response	Fetching top-up plans and applying top-up

Rate Limits

The API enforces the following limits to ensure fair usage across all partners.

Endpoint type	Limit
Read endpoints (GET)	120 requests / minute per API key
Write endpoints (POST)	30 requests / minute per API key
Top-up endpoints	20 requests / minute per API key

ℹ

If you exceed these limits you will receive a 429 Too Many Requests response. Implement exponential backoff and retry after the Retry-After header value in seconds. Contact support if your platform requires higher limits.

Authentication

All API requests must be authenticated using your API key as a Bearer token in the Authorization header.

API Keys

Generate your API key from Partner Portal → API Access. Keys are prefixed with tvr_ and are shown only once at generation — store them securely.

All Requests

# Include in every request header
Authorization: Bearer tvr_your_api_key_here

⚠

Keep your key secretNever expose your API key in frontend JavaScript or public repositories. Use it server-side only. If compromised, generate a new key from the portal immediately.

Key Management

From your partner portal you can generate multiple keys, label them by environment (e.g. Production, Staging), and revoke them at any time. If you lose a key, simply generate a new one — your old key remains active until explicitly revoked.

Quick Start

Get your first eSIM order live in under 10 minutes.

Step 1 — Check your balance

cURL

curl https://api.tavaroesim.com/v1/balance \
  -H "Authorization: Bearer tvr_your_key"

Step 2 — Browse countries

cURL

curl https://api.tavaroesim.com/v1/countries \
  -H "Authorization: Bearer tvr_your_key"

Step 3 — Get plans for a country

cURL

curl "https://api.tavaroesim.com/v1/packages?country=AE" \
  -H "Authorization: Bearer tvr_your_key"

Step 4 — Place an order

cURL

Node.js

Python

curl -X POST https://api.tavaroesim.com/v1/order \
  -H "Authorization: Bearer tvr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"planId":"esim-uae-7days-5gb-all","customerEmail":"guest@example.com","customerName":"John Smith"}'

const res = await fetch('https://api.tavaroesim.com/v1/order', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tvr_your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    planId: 'esim-uae-7days-5gb-all',
    customerEmail: 'guest@example.com',
    customerName: 'John Smith'
  })
});
const { data } = await res.json();
const qrCode = data.esims[0].qrCodeUrl; // Send to customer

import requests

res = requests.post('https://api.tavaroesim.com/v1/order',
  headers={
    'Authorization': 'Bearer tvr_your_key',
    'Content-Type': 'application/json'
  },
  json={
    'planId': 'esim-uae-7days-5gb-all',
    'customerEmail': 'guest@example.com',
    'customerName': 'John Smith'
  }
)
qr_code = res.json()['data']['esims'][0]['qrCodeUrl']

Step 5 — Deliver to customer

Response

{
  "status": "success",
  "data": {
    "orderId": "tvr-api-1234567890",
    "totalCost": 12.99,
    "creditsRemaining": 487.01,
    "esims": [{
      "iccid": "8948010010026159235",
      "qrCodeUrl": "https://...",       ← Show/email to customer
      "iosInstallUrl": "https://esimsetup.apple.com/...",  ← 1-tap iPhone install
      "lpaCode": "LPA:1$smdp.io$K2-XXXXX",  ← Android manual entry
      "status": "READY"
    }]
  }
}

✓

That's it. Send qrCodeUrl or iosInstallUrl to your customer — they install in under 2 minutes.

Countries

List all countries and regions with available eSIM plans, including network types and carrier information.

GET /v1/countries List available countries

Query Parameters

geography

stringoptional

Filter by local, regional, or global

Response

{
  "status": "success",
  "data": {
    "countries": [
      {
        "name": "United Arab Emirates",
        "code": "AE",
        "geography": "local",
        "region": "Middle East",
        "planCount": 14,
        "fromPrice": 7.06,
        "networks": ["4G", "LTE", "5G"],
        "carriers": ["DU", "Etisalat"],
        "countriesCovered": 1  // >1 for regional/global plans
      }
    ]
  }
}

Response Fields

Field	Type	Description
name	string	Country name
code	string	ISO 3166-1 alpha-2 code (e.g. AE, IN, GB)
geography	string	`local`, `regional`, or `global`
planCount	number	Number of available plans
fromPrice	number	Lowest plan price at your markup (USD)
networks	array	Supported network types e.g. ["4G","LTE","5G"]
carriers	array	Network operators e.g. ["DU","Etisalat"]
countriesCovered	number	For regional/global: number of countries included

Packages

Browse eSIM plans for a specific country or region. Use the planId to place an order.

GET /v1/packages List eSIM plans

Query Parameters

country

stringoptional

ISO country code e.g. AE, IN, GB

geography

stringoptional

Filter by local, regional, or global

days

numberoptional

Filter by validity period e.g. 7, 14, 30

Response

{
  "status": "success",
  "data": {
    "packages": [{
      "countryName": "United Arab Emirates",
      "countryCode": "AE",
      "geography": "local",
      "coverage": [{
        "country": "United Arab Emirates",
        "networks": ["4G", "LTE", "5G"],
        "carriers": ["DU", "Etisalat"]
      }],
      "plans": [{
        "planId": "esim-uae-7days-5gb-all",
        "name": "5 GB - 7 Days",
        "days": 7,
        "data": "5GB",
        "price": 12.99,
        "currency": "USD",
        "activation": "first-use",
        "isUnlimited": false,
        "hotspot": true,
        "dataRoaming": true,
        "topUp": false,
        "networks": ["4G", "LTE", "5G"],
        "carriers": ["DU", "Etisalat"],
        "throttle": null
      }]
    }]
  }
}

Plan Fields

Field	Type	Description
planId	string	Unique plan ID — use this in /v1/order
days	number	Validity period in days
data	string	Data amount e.g. "5GB" or "Unlimited"
price	number	Price at your markup (USD)
activation	string	`first-use` — starts when customer first uses data
hotspot	boolean	Whether hotspot/tethering is supported
dataRoaming	boolean	Whether data roaming is included
topUp	boolean	Whether the plan supports top-up
networks	array	Network types e.g. ["4G","LTE","5G"]
carriers	array	Carrier names e.g. ["DU","Etisalat"]
coverage	array	Per-country breakdown for regional/global plans
throttle	object\|null	FUP details if applicable, null if no throttle

Place Order

Purchase an eSIM plan. Credits are deducted from your balance instantly. The eSIM is activated and returned in the response — no additional activation step needed.

ℹ

Credits deducted at partner rateYour credits are deducted at your partner price. Your api_markup (set in portal) is applied to price shown in /v1/packages but not deducted from your credits.

POST /v1/order Purchase an eSIM

Request Body (JSON)

planId

stringrequired

Plan ID from /v1/packages

customerEmail

stringrequired

Customer's email address — for records and support

customerName

stringoptional

Customer's full name

quantity

numberoptional

Number of eSIMs to purchase. Default: 1, Max: 10

Request

{
  "planId": "esim-uae-7days-5gb-all",
  "customerEmail": "john.smith@example.com",
  "customerName": "John Smith",
  "quantity": 1
}

Response

{
  "status": "success",
  "data": {
    "orderId": "tvr-api-1234567890",
    "planId": "esim-uae-7days-5gb-all",
    "quantity": 1,
    "unitPrice": 0.79,
    "totalCost": 0.79,
    "currency": "USD",
    "creditsRemaining": 199.21,
    "esims": [{
      "esimId": "dc4f98d8-e810-4c72-9d1a",
      "iccid": "8948010010026159235",
      "lpaCode": "LPA:1$smdp.io$K2-2WVWVT-ORZRRT",
      "smdpAddress": "smdp.io",
      "activationCode": "K2-2WVWVT-ORZRRT",
      "qrCodeUrl": "https://imagedelivery.net/...",
      "iosInstallUrl": "https://esimsetup.apple.com/...",
      "status": "READY"
    }]
  }
}

Delivering to your customer

Field	Use
qrCodeUrl	Display as QR image or email to customer to scan
iosInstallUrl	One-tap install link for iPhone users
lpaCode	Manual entry for Android: Settings → SIM → Add eSIM
iccid	Unique eSIM identifier — save for support queries

eSIM Status

Check the current status of a purchased eSIM using the esimId returned from an order.

GET /v1/esim/:esimId Get eSIM status

Path Parameters

esimId

stringrequired

The esimId returned from /v1/order

eSIM Statuses

Status	Meaning
READY	Installed but not yet activated — waiting for first data use
ACTIVE	Currently in use, data being consumed
EXPIRED	Validity period has ended
DEPLETED	Data fully consumed before expiry

Balance

Check your current Tavaro Credits balance. Use this to verify available funds before placing bulk orders.

GET /v1/balance Get credit balance

Response

{
  "status": "success",
  "data": {
    "balance": "487.01",
    "currency": "USD",
    "company": "TripFactory Pvt Ltd"
  }
}

Top-up Plans

Retrieve compatible top-up plans for an existing eSIM using its ICCID. Only plans where topUp: true in /v1/packages will appear here.

GET /v1/esim/topup/packages Get compatible top-up plans for an eSIM

Query Parameters

iccid

stringrequired

The ICCID of the eSIM to top up. Retrieved from the original /v1/order response.

ℹ

Top-up eligibilityNot all eSIMs support top-up. Only plans originally purchased with a top-up–compatible package will return results. If the array is empty, top-up is not available for that eSIM.

cURL

curl "https://api.tavaroesim.com/v1/esim/topup/packages?iccid=8948010010026159235" \
  -H "Authorization: Bearer tvr_your_key"

Response

{
  "status": "success",
  "data": {
    "iccid": "8948010010026159235",
    "packages": [
      {
        "packageId": "esim-uae-7days-5gb-topup",
        "name": "UAE 5 GB · 7 Days",
        "days": 7,
        "data": "5 GB",
        "price": 9.50,
        "currency": "USD",
        "hotspot": true,
        "networks": ["4G LTE", "5G"]
      }
    ]
  }
}

Response Fields

Field	Type	Description
iccid	string	The ICCID of the eSIM queried
packages	array	List of compatible top-up plans
packages[].packageId	string	Use this ID when calling `POST /v1/esim/topup`
packages[].name	string	Human-readable plan name
packages[].days	number	Validity in days from activation of top-up
packages[].data	string	Data allowance (e.g. `5 GB`, `Unlimited`)
packages[].price	number	Cost in USD deducted from your credits
packages[].hotspot	boolean	Whether hotspot / tethering is supported
packages[].networks	array	Supported network types (e.g. 4G LTE, 5G)

Apply Top-up

Apply a top-up plan to an existing eSIM. Credits are deducted immediately and data is added to the eSIM instantly.

POST /v1/esim/topup Apply a top-up to an eSIM

Request Body (JSON)

iccid

stringrequired

The ICCID of the eSIM to top up.

packageId

stringrequired

The packageId from GET /v1/esim/topup/packages.

⚠

Irreversible actionTop-ups are applied instantly and credits are deducted immediately. Always confirm the ICCID and packageId before calling this endpoint. There is no rollback once applied.

cURL

Node.js

curl -X POST https://api.tavaroesim.com/v1/esim/topup \
  -H "Authorization: Bearer tvr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"iccid":"8948010010026159235","packageId":"esim-uae-7days-5gb-topup"}'

Response

{
  "status": "success",
  "data": {
    "iccid": "8948010010026159235",
    "packageId": "esim-uae-7days-5gb-topup",
    "cost": 9.50,
    "currency": "USD",
    "creditsRemaining": 477.51
  }
}

Response Fields

Field	Type	Description
iccid	string	ICCID of the eSIM that was topped up
packageId	string	The package that was applied
cost	number	Credits deducted for this top-up (USD)
currency	string	Always `USD`
creditsRemaining	number	Your updated balance after deduction

✓

Instant activationData is added to the eSIM immediately after a successful response. No polling required.

Errors

All errors return a consistent JSON structure. Always check the status field first.

Error Format

{
  "status": "error",
  "message": "Insufficient credits. Available: $12.00, Required: $24.99"
}

HTTP Status Codes

400Bad RequestMissing required field (e.g. planId or customerEmail)

401UnauthorizedMissing or invalid API key

402Insufficient CreditsNot enough credits — top up your balance

403ForbiddenAccount suspended — contact support

404Not FoundPlan ID not found or no longer available

429Too Many RequestsRate limit exceeded — check Retry-After header and retry

500Server ErrorTemporary issue — retry after a few seconds

⚠

Handle 402 gracefullyCheck your balance before bulk orders using /v1/balance. A 402 means the order was not placed and no credits were deducted.

Postman Collection

Import our Postman collection to test all API endpoints instantly — no setup required.

ℹ

Coming soonWe're preparing a public Postman collection. In the meantime, use the cURL examples throughout this documentation or import manually using the endpoint details below.

Manual Setup

Set up a Postman environment with these variables:

Variable	Value
base_url	https://api.tavaroesim.com
api_key	tvr_your_key_here

Then use Authorization: Bearer {{api_key}} as a collection-level header.

Integration Guide

Recommended approach for integrating Tavaro eSIM into a travel booking platform.

Recommended Flow

1

Cache countries list

Call /v1/countries once daily and cache. Countries and regions change infrequently.

2

Fetch packages on demand

When a customer selects a destination, call /v1/packages?country=XX. Cache per country for up to 1 hour.

3

Display plans with coverage

Show data, days, price, hotspot, and networks. For regional plans, show coverage array to list included countries.

4

Place order server-side only

Never call /v1/order from frontend. Always from your backend — your API key must stay secret.

5

Deliver eSIM

Show qrCodeUrl on confirmation page. Email iosInstallUrl and lpaCode for manual install. Save iccid in your database.

6

Monitor balance

Set up automated alerts when balance drops below a threshold using /v1/balance.

B2B Travel Agent Flow

For platforms where agents book on behalf of travellers (e.g. Nexus DMC):

Step	Action
Agent selects destination	Show eSIM plans via /v1/packages
Agent enters traveller details	Collect traveller email for eSIM delivery
Confirm booking	Call /v1/order with traveller's email as customerEmail
Deliver eSIM	Email QR code directly to traveller or to agent to forward

✓

Device compatibilityBefore displaying eSIM as an option, check if the customer's device supports eSIM. Most modern smartphones (iPhone XS+, Samsung S20+, Pixel 3+) are compatible. Huawei and some Chinese-market variants are not.

Support

Our team is available to help you integrate successfully and answer any technical questions.

💬

Fastest response — under 5 mins

Chat on WhatsApp

📧

Email

Within 4 business hours

api@tavaroesim.com

✓

Partner onboardingNew partners get a dedicated onboarding call with our team. We'll walk through the integration, set up your account, and get you live as quickly as possible. Get started →