Integrate the eSIM API
Use the eSIM API to purchase data packages and manage installation and top-ups. You need a workspace, an API key with the required permissions, and wallet funds for live purchases. Follow authentication and select the API region for your workspace before sending requests.
1. Choose an offer
List offers for the destination, then get the selected offer. Check its coverage countries, allowance, validity, and published price. Save the offer ID and revision with the price shown to your customer.
For an existing eSIM, use List compatible offers. An offer in the general catalog may not work as a top-up on that profile. For automatic renewal, follow the recurring-package guide.
2. Create the purchase
Create an order with offer_id. Omit esim_id for a new profile; include it to buy a top-up. For a one-time purchase, send offer_revision and expected_price to reject a changed quote before charging. Save a unique Idempotency-Key for this purchase and reuse it with the same request when recovering a lost response.
Store the returned order ID. Inspect status even after HTTP 201, which can carry a completed or failed order. HTTP 202 means processing continues. Get the order until its status is completed or failed. A completed order identifies the eSIM and package. Installation and usable mobile data are separate outcomes.
3. Provide installation details
After purchase, read the installation credentials, create a hosted installation link, or send an installation link by email or SMS. Credential operations require the separate esim_credentials permission. Keep activation details and installation links out of analytics and public logs.
If you send a link, check delivery history for its outcome. Acceptance for sending does not confirm delivery or device installation. Follow the installation guide to verify setup on a compatible device.
4. Recover an interrupted purchase
Read an existing order before buying again. If the create response was lost, repeat the original request with its original Idempotency-Key; see idempotent requests. Do not change the key to work around an uncertain outcome.
An order in charging may be awaiting wallet funds. Check funding when present and your current balance. One-time orders retry funding automatically. After an initial recurring purchase is refused for insufficient funds, add funds and explicitly retry the same create request. Use Cancel an order if you no longer want an unfunded purchase; read its cancellation rules before assuming a paid package was canceled.
For a failed purchase, inspect failure_code and failure_reason. Any charge is credited automatically; refund_transaction_id identifies an issued credit. Contact support with the order ID if the payment or delivery outcome remains unresolved.
5. Show balances and service state
Get the eSIM for status, installation state, packages, and current available actions. Check the package balance timestamp before displaying consumption. A null measurement means usage is unknown. Daily usage history is not currently available.
Use the usage and top-ups guide to replenish data and the operations guide to investigate an issue. Recheck action availability when the customer acts; a previous response does not guarantee that a later request will succeed.
Next steps
Related resources
Continue with the documentation, guides and examples for this topic.