---
title: "bird esim orders create"
description: "Order a data package"
canonical: "https://bird.com/docs/cli/reference/esim-orders-create"
---

# `bird esim orders create`

## Usage

```bash
bird esim orders create [flags]
```

## Description

Order a data package

Purchase an eSIM data package. Without esim\_id a new eSIM is provisioned with the package; with esim\_id the package is added to that eSIM. The order locks the offer's price at creation. Inspect status even on HTTP 201: the order can be completed or failed. On HTTP 202, poll until completed or failed. Omit delivery; after completion use `bird esim credentials deliver` to send install credentials to the traveler.

Build the request from flags, a JSON EsimOrderCreate body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

Browser confirmation: the review link goes to stderr, not stdout, as next[].url
in a JSON line that also carries confirmation\_id. The command then waits and
prints the result on stdout; --confirmation-id waits on an existing one.

## Procedure

Step 5 of 8 of "Buy and install an eSIM data package". Previous: bird esim offers requirements. Next: bird esim orders get.

## Examples

```bash
# print the body shape (no credentials needed)
bird esim orders create --example

# the body it prints:
```

```json
{
  "display_name": "Amsterdam trip, order 8812",
  "offer_id": "eof_01krdgeqcxet5s7t44vh8rt9mg"
}
```

## Options

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                               | Description                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--offer-id`                       | Offer to purchase. (required; or in --body-file)                                                                                                                                                                                                                                                                                                |
| `--esim-id`                        | Existing eSIM to add the package to. Omit to provision a new eSIM.                                                                                                                                                                                                                                                                              |
| `--subscriber-id`                  | Person 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-revision <n>`             | The 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.                                                                                                                   |
| `--display-name`                   | Free-text label for the new eSIM, for your own reference. Ignored when esim\_id is set.                                                                                                                                                                                                                                                         |
| `--tags <key=value>`               | Tags for the new eSIM, echoed on its lifecycle webhook events. Ignored when esim\_id is set.                                                                                                                                                                                                                                                    |
| `--metadata`                       | Your 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-validity` | Set 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-schema`                | Print the fields this command returns, then exit                                                                                                                                                                                                                                                                                                |
| `--confirmation-id`                | Wait for an existing confirmation of this exact request                                                                                                                                                                                                                                                                                         |

## Related

| Name                                                                | Description              |
| ------------------------------------------------------------------- | ------------------------ |
| [`bird esim orders cancel`](/docs/cli/reference/esim-orders-cancel) | Cancel an unfunded order |
| [`bird esim orders get`](/docs/cli/reference/esim-orders-get)       | Get an order             |
| [`bird esim orders list`](/docs/cli/reference/esim-orders-list)     | List orders              |

## 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)