# [Integrate the eSIM API](/content/docs/guides/esim/api#integrate-the-esim-api/index.html)

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](/content/docs/api/authentication/index.html) and use the [API region](/content/docs/api/regions/index.html) 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](/content/docs/guides/esim/api#1-choose-an-offer/index.html)

[List offers](/content/docs/api/reference/list-esim-offers/index.html) for the destination, then [get the selected offer](/content/docs/api/reference/get-esim-offer/index.html). Check `zone.countries`, the allowance and validity in `pricing`, speed terms, and any included phone service. For an existing eSIM, use [List compatible offers](/content/docs/api/reference/list-esim-compatible-offers/index.html); general catalog availability does not establish top-up compatibility.

[Get the offer's identification requirements](/content/docs/api/reference/get-esim-offer-requirements/index.html) 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](/content/docs/api/reference/get-esim-offer-checkout-options/index.html). 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](/content/docs/guides/esim/mobile-plans/index.html) 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:

### Code example

```bash
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](/content/docs/guides/esim/api#2-create-the-purchase/index.html)

[Create an order](/content/docs/api/reference/create-esim-order/index.html) 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:

### Code example

```bash
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](/content/docs/guides/esim/mobile-plans#2-assign-the-subscriber/index.html). 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](/content/docs/api/reference/get-esim-order/index.html) 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](/content/docs/guides/esim/api#3-provide-installation-details/index.html)

After purchase, [read installation credentials](/content/docs/api/reference/get-esim-credentials/index.html), [create a hosted installation link](/content/docs/api/reference/create-esim-install-link/index.html), or [send a link](/content/docs/api/reference/deliver-esim-credentials/index.html) 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](/content/docs/api/reference/list-esim-deliveries/index.html). A `202` response confirms acceptance for sending; `delivered` confirms message delivery, and device installation needs its own check. Follow the [installation guide](/content/docs/guides/esim/installation/index.html) for supported methods, link expiry, and recovery.

## [4. Recover an interrupted purchase](/content/docs/guides/esim/api#4-recover-an-interrupted-purchase/index.html)

If the create response was lost or returned `503`, repeat the saved request with its original `Idempotency-Key`; see [idempotent requests](/content/docs/api/idempotency/index.html). 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](/content/docs/api/reference/cancel-esim-order/index.html). 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](/content/docs/guides/esim/api#5-show-balances-and-service-state/index.html)

[Get the eSIM](/content/docs/api/reference/get-esim/index.html) for status, installation state, packages, and `available_actions`. Display the package's allowance, consumption, and observation time using the [usage guide](/content/docs/guides/esim/usage-and-top-ups/index.html). 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](/content/docs/guides/esim/operations/index.html) to investigate incomplete purchases, installation problems, or connectivity failures.

## [Next steps](/content/docs/guides/esim/api#next-steps/index.html)

- [Choose a travel package](/content/docs/guides/esim/travel/index.html).
- [Prepare device installation](/content/docs/guides/esim/installation/index.html).
- [Manage recurring packages](/content/docs/guides/esim/mobile-plans/index.html).
