---
title: "Get an order"
method: GET
path: "/v1/esim/orders/{order_id}"
tags: ["esims"]
---

# Get an order

`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`

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

## Path parameters

- `order_id` string, required

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

The order.

- EsimOrder: One purchase: a new eSIM with its first package, or an additional package on an existing eSIM. The order locks the quote at creation (the offer revision and the exact price) and is the durable record of the purchase: poll it until a terminal status when it does not complete inline. Orders that can be served immediately complete within the request.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `id` string, 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_id` string, required
  - `offer_revision` integer, 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_id` string, required
  - `esim_id` string, required
  - `subscriber_id` string, required
  - `recurring_subscription_id` string
  - `package_id` string, required
  - `price` Money, required
    - `amount` string, required: Decimal amount as a string, in major currency units.
    - `currency_code` string, required: ISO 4217 three-letter currency code.
  - `wallet_transaction_id` string, required
  - `refund_transaction_id` string, required
  - `delivery` EsimDelivery: Where and how install credentials reach the traveler. The recipient is a raw address, so delivery works for travelers who are not stored anywhere: an email address for email, an E.164 phone number for sms.
    - `to` string, required: Recipient address. An email address for the email channel, an E.164 phone number for the sms channel.
    - `channel` 'email' | 'sms', required: Channel the install credentials are delivered over.
    - `locale` string: A language tag in BCP-47 form, for example `en` or `pt-BR`.
  - `awaiting_funds` boolean: 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.
  - `funding` EsimOrderFunding, required: Funding needed for an order in `charging`. Add funds to the wallet and retry the existing order. One-time orders also retry automatically. A funded order proceeds to delivery; a failed order receives an automatic credit for any charge.
    - `required_amount` Money, required
      - `amount` string, required: Decimal amount as a string, in major currency units.
      - `currency_code` string, required: ISO 4217 three-letter currency code.
    - `lapses_at` string, date-time, required: Earliest time a further insufficient-funds attempt can fail the order. Adding funds after this time can still complete the purchase before that attempt. Check the order status to determine whether it remains payable.
  - `failure_code` string, 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_reason` string, nullable, required: Why the order failed, in plain terms. Null unless status is failed.
  - `completed_at` string, date-time, nullable, required: When the order reached completed. Null before that.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)