esims

Cancel an unfunded order

Cancels an order waiting for funds in charging. A canceled unfunded order returns status: failed with failure_code: canceled. If a charge is confirmed after cancellation, it is credited back automatically.

For a one-time order, payment confirmed before cancellation returns 409, and the purchase continues. For an initial recurring purchase, payment recovered during cancellation instead stops future renewal and returns the current order successfully. The paid package continues to delivery without an automatic refund. Inspect the returned order and its subscription to determine the outcome.

Orders already completed, failed, or past the funding stage cannot be canceled through this operation and return 409.

post/v1/esim/orders/{order_id}/cancel

Request

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

Path parameters

order_idstring required
Example:eor_01krdgeqcxet5s7t44vh8rt9mg

Order ID.

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

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 after cancellation. An unfunded order is failed with failure_code: canceled. For an initial recurring purchase whose payment was recovered, the paid order continues and future renewal is stopped.

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.