Embed eSIM connectivity in your app
Use this guide to connect an eSIM purchase to an account in your app. You need a Bird workspace, a server-side API integration, and a way to authenticate your customers. Follow the API guide for permissions and request details.
1. Show offers your customer can use
List offers for the customer's destination and show the selected offer's coverage, allowance, validity, and published price. Check device compatibility and identification requirements before purchase.
For automatic renewal, use the offer's checkout options to display the available purchase modes and accepted terms. Keep the offer revision and quoted price with the customer's selection. If the quote changes, show the new terms and ask the customer to accept them before buying.
2. Associate the purchase with your customer
Keep Bird API keys on your server. Authorize access to each order and eSIM using your app's customer account; a workspace API key can access resources belonging to multiple customers.
Store your customer ID with the order ID and, once delivered, the eSIM and package IDs. If you need a named service user or automatic renewal, create a subscriber from a workspace contact. Assignment records who uses the eSIM; it does not sign that person into your app or grant access to credentials.
Your organization wallet funds the Bird purchase. If you charge your customer separately, track that payment separately from the eSIM order so you can resolve a payment or delivery failure.
3. Create one recoverable purchase
Generate and store an Idempotency-Key before creating the order. Reuse that key with the same request if the response is interrupted.
Show a processing state until the order reaches a final outcome. Save the order before sending the customer to installation, and let them return to it from their account. For an unfunded or failed order, use the purchase recovery steps.
4. Deliver private installation instructions
After the order completes, create a hosted installation link for the intended customer or send the link by email or SMS. Follow the installation guide for delivery, expiry, revocation, and device setup.
Treat the link and activation details as credentials. Keep them out of analytics, public logs, and routine support notes. Record purchase completion, link delivery, and device installation as separate outcomes.
If you are replacing an existing connectivity service, plan a new Bird eSIM purchase and installation. Check the intended device and package before the customer changes their existing service. The Bird eSIM API does not import an existing profile or transfer a mobile number.
5. Add an account page for ongoing use
Let the authenticated customer reopen their existing eSIM, see reported package balances and expiry, and reach support. Display the balance timestamp and unknown values accurately.
Use compatible offers for top-ups and the eSIM's available_actions to decide which controls to display. Explain a disabled action using its returned reason, and handle a refusal if availability changes before submission. Follow the recurring-package guide for renewal and cancellation.
Verify interruption and recovery
Close the browser after purchase and reopen the customer's account. Confirm that it leads to the same order and eSIM. Repeat after installation starts.
Check that a lost purchase response, an expired installation link, and an unknown usage value each lead to an appropriate recovery action. Verify that one customer cannot open another customer's installation link or eSIM through your account page.
Next steps
Related resources
Continue with the documentation, guides and examples for this topic.