---
title: "List orders"
canonical: "https://bird.com/docs/api/reference/list-esim-orders"
---

# List orders

`GET /v1/esim/orders`

Returns the workspace's orders as a cursor-paginated list, newest first. Filter by `status` to find in-flight or failed purchases, by `esim_id` for one eSIM's purchase history, or by `mode` to separate test purchases from real ones. Test orders are listed alongside real ones by default, each carrying its own `mode`.

## Code samples

**CLI**

```sh
bird esim orders list
```

Examples: [CLI](/docs/api/reference/list-esim-orders.cli.md) · [MCP](/docs/api/reference/list-esim-orders.mcp.md) · [cURL](/docs/api/reference/list-esim-orders.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "created_at": "2026-05-20T09:14:52Z",
      "updated_at": "2026-05-25T16:42:01Z",
      "id": "eor_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "scheduled",
      "mode": "live",
      "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": "USD"
      },
      "wallet_transaction_id": "wtx_01krdgeqcxet5s7t44vh8rt9mg",
      "refund_transaction_id": "wtx_01krdgeqcxet5s7t44vh8rt9mg",
      "delivery": {
        "to": "traveler@example.com",
        "channel": "email",
        "locale": "pt-BR"
      },
      "funding": {
        "required_amount": {
          "amount": "0.00995",
          "currency_code": "USD"
        },
        "lapses_at": "2026-09-08T14:51:01Z"
      },
      "failure_code": "insufficient_balance"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Query parameters

- `limit` (integer): Maximum number of items to return per page.
- `starting_after` (string): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string): Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.
- `created_after` (string): Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset.
- `created_before` (string): Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset.
- `status` (array): Keep only orders whose `status` matches; repeat the parameter to match any of several.
- `esim_id` (string): Keep only orders for this eSIM.
- `mode` (string)

  Keep only orders created in this mode. Without it, both live and test orders are returned.

  Possible values: `live`, `test`
- `completed_after` (string): Keep only orders completed at or after this timestamp. Combine it with `completed_before` to select a completion window, which is what the analytics spend and completion figures are counted by; `created_after` selects when an order was placed instead. Orders that never completed are excluded. Use an RFC 3339 timestamp with a timezone offset.
- `completed_before` (string): Keep only orders completed before this timestamp. Combine it with `completed_after` to select a completion window. Orders that never completed are excluded. Use an RFC 3339 timestamp with a timezone offset.

## Response body

- `data` (array of object, required): Orders, newest first.
- `data.created_at` (string, required)
- `data.updated_at` (string, required)
- `data.id` (string, required)
- `data.status` (string, required)
- `data.mode` (string, required)
- `data.offer_id` (string, required): Offer purchased.
- `data.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.
- `data.zone_id` (string, required): Coverage zone of the purchased offer, captured at creation.
- `data.esim_id` (nullable string, required): The eSIM the package lands on. Set at creation when adding to an existing eSIM; set when provisioning starts for a new-eSIM order; null before that.
- `data.subscriber_id` (nullable string, required): Subscriber to assign when the new eSIM is delivered. Null when none was requested, including top-up orders, which retain the existing assignment.
- `data.recurring_subscription_id` (string): The recurring service associated with this purchase. Absent for one-time orders.
- `data.package_id` (nullable string, required): The purchased data package, set when the order completes; null before that.
- `data.price` (object, required): The quoted price, locked at creation in your billing currency. A `mode: test` order quotes this price and is never charged it, so its `wallet_transaction_id` stays null.
- `data.price.amount` (string, required): Decimal amount as a string, in major currency units.
- `data.price.currency_code` (string, required): ISO 4217 currency code.
- `data.wallet_transaction_id` (nullable string, required): The wallet transaction that paid for this order, for reconciling against your billing transactions. Null until the charge lands, and always null for a `mode: test` order, which is never charged.
- `data.refund_transaction_id` (nullable string, required): The wallet transaction that credited the charge back after a failure. Null unless the order failed after charging.
- `data.delivery` (object): Where install credentials are delivered once available. Present when requested at creation.
- `data.delivery.to` (string, required): Recipient address. An email address for the email channel, an E.164 phone number for the sms channel.
- `data.delivery.channel` (string, required)

  Channel the install credentials are delivered over.

  Possible values: `email`, `sms`
- `data.delivery.locale` (string): Language for the message. Falls back to the closest available language, then English.
- `data.funding` (nullable object, required): Details of an insufficient-funds attempt while the order is in `charging`. May be null even while the order is awaiting funds; a null value does not confirm payment. Check the order status and your wallet balance.
- `data.funding.required_amount` (object, required): Total wallet balance required for the charge, including tax. This is the required balance rather than the amount to add. Compare it with your current wallet balance.
- `data.funding.required_amount.amount` (string, required): Decimal amount as a string, in major currency units.
- `data.funding.required_amount.currency_code` (string, required): ISO 4217 currency code.
- `data.funding.lapses_at` (string, 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.
- `data.failure_code` (nullable string, 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.

  Possible values (may grow over time): `insufficient_balance`, `carrier_error`, `capacity_exhausted`, `offer_unavailable`, `internal_error`, `canceled`, `resolved_by_support`, `esim_released`, `mode_mismatch`
- `data.failure_reason` (nullable string, required): Why the order failed, in plain terms. Null unless status is failed.
- `data.completed_at` (nullable string, required): When the order reached completed. Null before that.
- `next_cursor` (nullable string, required): Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
- `prev_cursor` (nullable string, required): Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
- `refresh_cursor` (nullable string, required): Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)