Integrate the eSIM API

Use the eSIM API to purchase data packages and deliver installation details from your application. You need a workspace, an API key, and organization wallet funds for live purchases. Follow authentication and use the API region matching your key.

Give the key esim:read to inspect offers and resources, and esim:write to purchase or manage service. Installation credentials have separate permissions: esim_credentials:read to retrieve them and esim_credentials:write to create or send installation links. Keep the API key in your server application.

1. Choose an offer

List offers for the destination, then get the selected offer. Check zone.countries, the allowance and validity in pricing, speed terms, and any included phone service. For an existing eSIM, use List compatible offers; general catalog availability does not establish top-up compatibility.

Get the offer's identification requirements before collecting subscriber information. The response contains a JSON Schema for each coverage country, requiring first name, last name, and email, plus any additional fields. Enable email and date format validation. You collect and validate this information; the eSIM API does not receive or verify the answers, and successful validation does not authorize a purchase.

For a new eSIM, get checkout options. Show the returned one-time price or available recurring quote before accepting the purchase. Checkout prices are before tax. Renewal has its own price and cadence; follow recurring packages when the customer chooses it.

For the one-time example below, install curl and jq. Set BIRD_API_URL to your regional base URL, BIRD_API_KEY to your key, and ESIM_OFFER_ID to the selected offer ID:

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Review the price and offer terms before continuing. The quote does not reserve availability.

2. Create the purchase

Create an order with offer_id. Omit esim_id for a new profile; include it for a top-up. For a one-time purchase, send offer_revision and expected_price from the accepted quote. These fields reject changed terms with 409 before charging; fetch and review a fresh quote before accepting a changed price.

Set ESIM_ORDER_KEY to a unique value for this purchase and save it with the request. This example buys a new, unassigned eSIM and copies the published price without changing its amount or currency:

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

To assign a new profile when delivery completes, include a workspace subscriber_id; follow subscriber setup. A top-up retains the existing assignment, so omit subscriber_id when sending esim_id. Send installation details separately after delivery.

Store the returned order ID. Inspect status even after HTTP 201, which can contain a completed or failed order. HTTP 202 means processing continues. Get the order until it is completed or failed. A completed order identifies esim_id and package_id; device installation remains a separate step.

3. Provide installation details

After purchase, read installation credentials, create a hosted installation link, or send a link by email or SMS. Keep activation details and installation links out of analytics and public logs.

For a sent link, save the delivery ID and check delivery history. A 202 response confirms acceptance for sending; delivered confirms message delivery, and device installation needs its own check. Follow the installation guide for supported methods, link expiry, and recovery.

4. Recover an interrupted purchase

If the create response was lost or returned 503, repeat the saved request with its original Idempotency-Key; see idempotent requests. If you have the order ID, read that order first. Creating another purchase while the outcome is uncertain can cause another charge.

For an order in charging, inspect funding and your wallet balance. funding.required_amount is the total balance needed, including tax; compare it with existing funds before adding money. 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 with its original key.

Check the current order status even after funding.lapses_at: that timestamp does not guarantee cancellation. An order can still complete if it receives funds before a further insufficient-funds attempt fails it.

To stop an unwanted unfunded purchase, cancel the order. Successful unfunded cancellation returns status: failed and failure_code: canceled. A funded one-time order returns 409 and continues. For an initial recurring purchase, payment recovered during cancellation can leave the paid purchase continuing while future renewal stops. Inspect the returned order and subscription before reporting cancellation or a refund.

For a failed purchase, inspect failure_code and failure_reason. Any charge is credited automatically; refund_transaction_id identifies an issued credit. Keep the order ID for support if payment, delivery, or the credit remains unresolved.

5. Show balances and service state

Get the eSIM for status, installation state, packages, and available_actions. Display the package's allowance, consumption, and observation time using the usage guide. Unknown consumption must remain unknown in your application.

Recheck action availability when the customer acts; the operation checks permissions and state again. Use the operations guide to investigate incomplete purchases, installation problems, or connectivity failures.

Next steps

• Choose a travel package.
• Prepare device installation.
• Manage recurring packages.