Order a data package
/v1/esim/ordersbird esim orders create \
--display-name 'Amsterdam trip, order 8812' \
--offer-id eof_01krdgeqcxet5s7t44vh8rt9mgcurl -X POST "https://us1.platform.bird.com/v1/esim/orders" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg",
"display_name": "Amsterdam trip, order 8812"
}'{
"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"
}
Purchases a data package at the quoted price. Omit esim_id to create an eSIM, or provide it to add a compatible package to an existing eSIM. Use List compatible offers before ordering a top-up. After purchase, use Send install credentials to deliver installation details separately.
Inspect status even when the response is 201: the order can be completed or failed. A 202 response means processing continues; use Get an order to follow the outcome. Failed orders receive an automatic credit for any charge; refund_transaction_id identifies the credit once issued.
An order awaiting funds stays in charging. For a one-time purchase, funding retries automatically; for an initial recurring purchase, retry the same create request with the same Idempotency-Key after adding funds. For one-time purchases, pass offer_revision and expected_price to reject changed terms with 409. Recurring purchases accept their quote through recurrence. An incompatible top-up or shortened package validity returns 409; use acknowledge_shortened_validity to accept the latter. After a 503 or a lost response, retry the same request with the same Idempotency-Key.
Request Payload
offer_idOffer to purchase.
esim_idExisting eSIM to add the package to. Omit to provision a new eSIM.
expected_priceThe price you displayed to the buyer. When set and the workspace's current resolved price differs, the order is refused with a conflict instead of charging a different amount. Catches billing-rate changes, which move independently of the offer revision.
display_nameFree-text label for the new eSIM, for your own reference. Ignored when esim_id is set.
tagsTags for the new eSIM, echoed on its lifecycle webhook events. Ignored when esim_id is set.
metadataYour own key-value data for the new eSIM, echoed on its lifecycle webhook events. Maximum 2 KB serialized. Ignored when esim_id is set.
acknowledge_shortened_validitySet to true to accept a validity cut short by the eSIM's service period. Without it, an order whose package would expire early is refused with a conflict that states the effective validity.
offer_idOffer to purchase.
esim_idExisting eSIM to add the package to. Omit to provision a new eSIM.
subscriber_idPerson to assign the new eSIM to when delivery completes. Must be a subscriber in this workspace. Omit to leave it unassigned. Supplying it with esim_id returns 422; top-ups retain the existing assignment. An unknown subscriber or one outside this workspace returns 404 before charging. Identification guidance does not gate purchase.
offer_revisionThe offer revision you are quoting from. When set and the offer has since moved to a newer revision, the order is refused with a conflict instead of charging a price you did not see. Omitted, the current revision is used.
recurrenceBuy the first package and enable automatic renewal in one purchase. Requires subscriber_id, offer_revision and Idempotency-Key. Omit esim_id and expected_price.
Show child parameters
recurrence.recurrence_revisionThe accepted recurring configuration revision.
recurrence.accepted_priceexpected_priceThe price you displayed to the buyer. When set and the workspace's current resolved price differs, the order is refused with a conflict instead of charging a different amount. Catches billing-rate changes, which move independently of the offer revision.
display_nameFree-text label for the new eSIM, for your own reference. Ignored when esim_id is set.
tagsTags for the new eSIM, echoed on its lifecycle webhook events. Ignored when esim_id is set.
metadataYour own key-value data for the new eSIM, echoed on its lifecycle webhook events. Maximum 2 KB serialized. Ignored when esim_id is set.
acknowledge_shortened_validitySet to true to accept a validity cut short by the eSIM's service period. Without it, an order whose package would expire early is refused with a conflict that states the effective validity.
Response Payload
created_atupdated_atidstatusmodeoffer_idOffer purchased.
offer_revisionRevision 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_idCoverage zone of the purchased offer, captured at creation.
esim_idThe 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.
subscriber_idSubscriber to assign when the new eSIM is delivered. Null when none was requested, including top-up orders, which retain the existing assignment.
recurring_subscription_idThe recurring service associated with this purchase. Absent for one-time orders.
package_idThe purchased data package, set when the order completes; null before that.
priceThe 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.
wallet_transaction_idThe 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.
refund_transaction_idThe wallet transaction that credited the charge back after a failure. Null unless the order failed after charging.
deliveryWhere install credentials are delivered once available. Present when requested at creation.
fundingDetails 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.
failure_codeReason 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
failure_reasonWhy the order failed, in plain terms. Null unless status is failed.
completed_atWhen the order reached completed. Null before that.
Related resources
Continue with the documentation, guides and examples for this topic.