Bino Supply · eSIM API
Search plans, activate, and deliver eSIM — through one supply API.
Browse multi-carrier eSIM plans by country or natural language, activate with a single order call, receive ICCID and QR code via webhook, and track usage and expiry — without managing direct carrier integrations.
eSIM supply layer
Search · Order · Activate · Monitor
POST
/esim/search
locationCode, type, filters
POST
/esim/searchai
query: "eSIM for Japan"
POST
/esim/order
binoTransactionId, items[]
POST
/esim/webhook
ORDER_STATUS · ESIM_STATUS
—
→ ICCID + QR code
on GOT_RESOURCE event
Capabilities
One API surface from catalog to connected customer.
Bino Supply abstracts multi-carrier eSIM procurement behind a single interface. Catalog search, AI discovery, order placement, webhook lifecycle, and QR code delivery all operate through the same API contract — BASE and TOPUP plans included.
Plan catalog search
Query available eSIM plans by ISO country code, region (!RG), or global (!GL). Filter by plan type (BASE or TOPUP), data volume, validity, and speed. Each result includes packageCode, price, data in bytes, duration unit, and topup eligibility.
AI-powered discovery
POST a natural language query like 'eSIM for Japan and Korea trip' and the API extracts destination country codes, fetches plans for each, deduplicates, and returns a merged catalog response — no manual filter mapping needed.
Instant order placement
POST an order with a binoTransactionId and one or more packageCode + quantity items. The API validates, fetches live pricing, and submits to the supply provider — returning an order reference and SUBMITTED status synchronously.
ICCID and QR code delivery
When the provider marks an order GOT_RESOURCE, the adapter queries the eSIM profile and returns ICCID, QR code URL, and LPA activation string — ready for delivery to the end customer via WhatsApp, push, or in-app.
Webhook event stream
Receive ORDER_STATUS, ESIM_STATUS, DATA_USAGE, and VALIDITY_USAGE events from the supply layer. Use these to trigger customer notifications, auto-renew flows, support escalations, or operational dashboards.
BASE and TOPUP plans
BASE plans create a new eSIM profile with a fresh activation. TOPUP plans add data to an existing active eSIM. Both plan types are searchable, orderable, and webhookable through the same API contract.
Multi-country and global bundles
Coverage spans individual country plans, regional multi-country bundles, and global plans in one catalog. The same search and order endpoints handle all coverage types — no separate flows per region.
Plan schema
Every plan carries what your product needs.
The catalog response returns a structured plan object for each available package. All fields are ready to render in a UI, pass to an order call, or use for filtering and sorting.
packageCode
Unique plan identifier for ordering
name / name_title
Display name, e.g. "1 GB for 7 DAY(s)"
price
Price in USD (provider price + 20% supply margin)
data_volume_bytes
Raw data quota in bytes
validity_duration + unit
Plan length, e.g. 7 DAY or 30 DAY
locations_covered
ISO country code, region code, or "Global"
speed
Network speed tier, e.g. 4G / LTE
is_top_up_supported
Whether TOPUP orders can extend this plan
activeType
Activation trigger: first install or first network connection
Activation flow
Order is synchronous. ICCID delivery is webhook-driven.
Order placement returns a provider reference immediately. The supply layer then fulfils the eSIM asynchronously and fires a GOT_RESOURCE webhook — at which point the adapter fetches and forwards the full profile: ICCID, QR code URL, and LPA activation string.
Search catalog
POST /esim/search with locationCode (ISO country, !RG, or !GL), plan type BASE or TOPUP, and optional filters. Or use /esim/searchai with a natural language query string.
Place order
POST /esim/order with binoTransactionId and an items array of packageCode + quantity. Receive providerOrderReference and SUBMITTED status.
Receive GOT_RESOURCE webhook
Provider fires ORDER_STATUS webhook when the eSIM is ready. Adapter auto-queries the profile — ICCID, QR code URL, and LPA activation string.
Deliver to customer
Push QR code and activation string to the customer via WhatsApp, app push, or in-chat message. Customer scans and connects.
Four webhook events cover the full eSIM lifecycle.
The supply layer emits events for order readiness, activation state, data consumption, and validity expiry. Subscribe to each to drive customer notifications, TOPUP triggers, and support escalations without polling.
ORDER_STATUS
GOT_RESOURCE
Order fulfilled by provider — trigger profile fetch to retrieve ICCID, QR code, and activation string.
ESIM_STATUS
Profile state change
eSIM ICCID and SM-DP+ (smdpStatus) state update — useful for tracking activation progress or detecting failures.
DATA_USAGE
Remaining bytes
Provider pushes current remaining data bytes for an ICCID — use to notify customers or trigger top-up flows.
VALIDITY_USAGE
Remaining validity
Provider pushes remaining validity duration and unit — use to warn customers before plan expiry.
Travel retail, enterprise, IoT, and reseller workflows.
The same search, order, and webhook surface handles individual consumer retail, bulk corporate provisioning, IoT device connectivity, and embedded B2B catalogs. The supply layer stays abstracted regardless of use case.
Travel eSIM retail via WhatsApp
Customer sends destination and dates. AI search returns matching plans. Customer picks, pays, receives QR code in the same WhatsApp conversation — no app install required.
Corporate data fleet
Manage eSIM plans for field teams and sales reps across cities and countries. Order, track usage, and renew via API without manual SIM logistics.
IoT device provisioning
Provision and manage data connectivity for connected devices, trackers, and sensors using the same BASE/TOPUP order surface — no separate carrier contracts.
B2B reseller platforms
Embed the eSIM catalog in travel portals, enterprise procurement tools, or operator dashboards. The supply layer stays abstracted behind Bino Supply.
Event and project connectivity
Issue short-validity eSIM plans for conference attendees, project teams, or temporary deployments. Order in bulk with distinct binoTransactionIds per recipient.
ICCID and QR code delivered. Customer scans and connects.
When the supply provider marks an order ready, the adapter returns the ICCID, QR code URL, and LPA activation string. Pipe that payload into a WhatsApp Cloud API message and the customer receives everything needed to activate — no app, no portal, no manual steps.
QR code + LPA string
Both activation methods returned. Customer can scan QR or enter the activation string manually on devices that support it.
BASE and TOPUP in one surface
Fresh activations and data top-ups share the same order endpoint. No separate carrier flow or contract per plan type.
Bow Chat eSIM support
Activation state, ICCID, and usage events flow into Bow Chat so support agents have full plan context without leaving the customer workspace.
FAQ
What is binoTransactionId and why is it required?
binoTransactionId is your system's unique reference for each order. It is used to track the order through the supply pipeline, correlate webhook events back to the original request, and prevent duplicate submissions. Use a UUID or your own order ID.
How does the AI search work?
The /esim/searchai endpoint accepts a plain-text query like "eSIM for Japan and South Korea". The adapter extracts ISO country codes using an AI model, runs a catalog search for each country in parallel, deduplicates by packageCode, and returns a merged plan list.
When do I receive the ICCID and QR code?
Not synchronously at order time. The provider fulfils the order asynchronously and fires an ORDER_STATUS webhook with orderStatus GOT_RESOURCE. When the adapter receives this, it queries the provider for the eSIM profile and returns the ICCID, QR code URL, and LPA activation string.
What is the difference between BASE and TOPUP plans?
BASE plans create a new eSIM profile on a new ICCID. TOPUP plans add data to an already-active eSIM. When ordering a TOPUP, the packageCode must be for a plan that supports top-up (is_top_up_supported: true in the catalog response).
What coverage does the catalog include?
Coverage is determined by the upstream supply provider and is returned dynamically in the catalog. You can search by any ISO Alpha-2 country code, use !RG for regional multi-country bundles, or !GL for global plans. Available countries and carriers are not hardcoded in the adapter.
How do I handle data-low or expiry alerts?
The provider sends DATA_USAGE webhooks with remaining bytes and VALIDITY_USAGE webhooks with remaining duration. Subscribe to these events to notify customers, trigger automatic TOPUP orders, or raise support tasks in Bow Chat.
Can this connect to Bow Chat for customer support?
Yes. eSIM activation state, ICCID, usage events, and expiry signals can flow into Bow Chat so support agents see live plan status when a customer raises an issue — without needing to check a separate portal.