esims

Get an order

Returns one order. Poll until status is completed or failed; a completed order names the eSIM and package it produced.

get/v1/esim/orders/{order_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/esim/orders/{order_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

order_idstring required
Example:eor_01krdgeqcxet5s7t44vh8rt9mg

Order ID.

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The order.

created_atstring date-time required
updated_atstring date-time required
idstring required
status'scheduled' | 'charging' | 'provisioning' | 'pending' | 'completed' | 'failed' | 'canceled' required

Order state.

  • scheduled: reserved for a future scheduled purchase; no charge has been made.
  • charging: payment is being obtained. If funds are insufficient, inspect funding and your wallet balance. One-time orders retry automatically; an initial recurring purchase requires an explicit retry after adding funds.
  • provisioning: the package is being provisioned during the request.
  • pending: the purchase continues after the request returns. Read the order again to check its outcome.
  • completed: delivery completed and the eSIM and package IDs are available. This does not confirm device installation. Terminal.
  • failed: delivery failed. Any charge is credited automatically; refund_transaction_id identifies an issued credit. Terminal.
  • canceled: reserved for a scheduled purchase withdrawn before execution. Canceling an unfunded order currently returns failed with failure_code: canceled.
mode'live' | 'test' required

Whether a purchase or eSIM is live or simulated. The mode is fixed when the order is created; the resulting eSIM retains it.

  • live: purchases service for use on a device and charges the wallet.
  • test: simulates a purchase without a charge or usable mobile service.

List responses can include both modes. Filter by mode when separating test activity from live purchases.

offer_idstring required
offer_revisioninteger required

Revision of the offer this order locked at creation. The quoted price stays that of this revision even if the offer changes later. The produced package snapshots its coverage at purchase; the zone's live country list governs new sales only.

zone_idstring required
esim_idstring required
subscriber_idstring required
recurring_subscription_idstring
package_idstring required
wallet_transaction_idstring required
refund_transaction_idstring required
awaiting_fundsboolean

Whether this order is in charging after an insufficient wallet balance refusal. The required balance is in funding when available. False does not confirm payment; check status and wallet_transaction_id. When absent, funding indicates a refusal if present; otherwise the funding state is unknown.

failure_codestring nullable required

Reason the order failed. Null unless status is failed. Handle unrecognized codes without assuming the purchase succeeded.

  • canceled: canceled while awaiting funds.
  • resolved_by_support: support closed an unresolved order as failed.
  • esim_released: the target profile became unavailable before delivery.
  • mode_mismatch: the purchase could not be fulfilled in its original live or test mode.

Any charge is credited automatically. Check refund_transaction_id to confirm an issued credit.

failure_reasonstring nullable required

Why the order failed, in plain terms. Null unless status is failed.

completed_atstring date-time nullable required

When the order reached completed. Null before that.

Example response

{
  "created_at": "2026-05-20T09:14:52Z",
  "updated_at": "2026-05-25T16:42:01Z",
  "id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
  "offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg",
  "zone_id": "ezn_01krdgeqcxet5s7t44vh8rt9mg",
  "esim_id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
  "subscriber_id": "esub_01krdgeqcxet5s7t44vh8rt9mg",
  "recurring_subscription_id": "ers_01krdgeqcxet5s7t44vh8rt9mg",
  "package_id": "epk_01krdgeqcxet5s7t44vh8rt9mg",
  "price": {
    "amount": "0.00995",
    "currency_code": "EUR"
  },
  "wallet_transaction_id": "wtx_01krdgeqcxet5s7t44vh8rt9mg",
  "refund_transaction_id": "wtx_01krdgeqcxet5s7t44vh8rt9mg",
  "delivery": {
    "to": "traveler@example.com",
    "locale": "pt-BR"
  },
  "funding": {
    "required_amount": {
      "amount": "0.00995",
      "currency_code": "EUR"
    },
    "lapses_at": "2026-09-08T14:51:01Z"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.