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

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

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

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 →