190+
Coverage countries
10–30 sec
QR code delivery
600+
Data plans
99.5%
Service uptime
Plan Types
GET /esim/plans returns the full catalog with filters by country, region, data allowance, and validity period.
Single Country
Multiple Countries
Worldwide
How eSIM Sales Work
Choose a Plan
GET /esim/plans — filter by destination country, data allowance, and validity period. The buyer selects the most suitable option.
Create an Order
POST /esim/orders — the API returns a QR code and SM-DP+ address for manual activation. The validity period does not start until the first connection.
Buyer Activates the eSIM
They scan the QR code in Settings → Mobile Data → Add eSIM. Ready to use in 1–2 minutes.
eSIM Lifecycle
Issued
The QR code has been created, but the eSIM has not yet been installed on the device.
Active
The device has connected to the network. The validity period and data usage countdown has started.
Topped Up
Additional data has been added or the validity period has been extended via POST /esim/{id}/topup.
Expired
The data allowance or validity period has ended. The esim.expired webhook has been sent.
Main Endpoints
Documentation
/esim/plans
Plan catalog with filters
/esim/plans/{id}
Plan details, coverage, and operators
/topup/validate
Validate the user account
/esim/orders
Create an order and receive a QR code
/esim/orders/{id}
Status, data usage, and validity period
/esim/{id}/topup
Add data or extend the validity period
/webhooks
Register a webhook URL
{
"plan_id": "eu-regional-20gb-30d",
"quantity": 1,
"zone_id": "8001",
"external_order_id": "your-order-555"
}{
"order_id": "esim_3nk8w..",
"status": "issued",
"qr_code_base64": "iVBORw0KGgo...",
"smdp_address": "1\$rsp.giapi.com\$ESIM-8KX2",
"iccid": "89011012012341234512",
"expires_after_activation_days": 30,
"data_gb": 20
}Technical Advantages
QR and SM-DP+ in One Response
Display the QR code for scanning or the SM-DP+ string for manual entry — both formats are included in the response body.
Active eSIM Top-Up
POST /esim/{id}/topup — add gigabytes or extend the validity period without a new purchase or reactivation.
Validity Starts on First Connection
The countdown starts not at the moment of purchase, but when the device first connects to the network via eSIM.
Webhook Events
esim.activated, esim.data_low with balance below 20%, and esim.expired — real-time lifecycle monitoring.
Device Compatibility
iPhone and iPad
iPhone XS and newer, iPad Pro (2018+), iPad Air (2019+), iPad mini (2019+). iOS 12.1 and above.
Android
Google Pixel 2+, Samsung Galaxy S20+, and most flagship devices from 2020 and newer with eSIM support.
Field is_esim_compatible in the Catalog
GET /esim/plans/{id} contains the list of compatible devices. We recommend showing it before payment to reduce refunds.
Frequently Asked Questions
When does the validity period start?
The validity period starts when the device first connects to the network via eSIM, not at the moment of purchase. This allows eSIMs to be sold in advance — for example, as a gift before a trip. The activated_at field in GET /esim/orders/{id} records the exact time.
Can an eSIM be used together with a physical SIM?
Yes, if the device supports Dual SIM. The buyer can keep their main SIM for calls and SMS, and use the eSIM for mobile data abroad.
What happens when the data allowance runs out?
Internet access stops working. The esim.data_low webhook is sent when less than 20% of data remains — this lets you offer a top-up in advance. Topping up via POST /esim/{id}/topup adds data without reinstalling the eSIM.
Can the eSIM be reinstalled on another device?
No — according to the GSMA standard, each QR code can only be used once and is linked to a specific device. This is an industry-standard limitation, not an API limitation.