> For the complete documentation index, see [llms.txt](https://bump.sh/zim/doc/esim-api/llms.txt)

# Create an Order

> POST /v2/orders
> 
> Unified order creation for one-off and top-up travel plans. The Order is paid the way your Account's billing is set up:
> * **Advance Pay** - debited from your Account's prepaid wallet. A
> wallet that does not cover `price × recipients` is refused with
> `INSUFFICIENT_BALANCE` and nothing is created; there is no card
> fallback. Defaults to the caller as recipient.
> * **Post-paid** - billed on your monthly post-paid invoice.
> `recipientUserNanoIDs` is required.
> * An Account billed by card only cannot order through the API and
> is refused with `PAYMENT_METHOD_NOT_ALLOWED`: ask your account
> manager to enable Advance Pay.
> 
> 
> One Order is created **per recipient**; the response describes the first one. Fulfilment is asynchronous: poll `GET /orders/{orderID}` until the status is `FULFILLED` (or `FAILED`).
> 
> To top up an existing Subscription set `type: TOP_UP`, `topUpSubscriptionNanoID`, and a `planID` taken from `GET /subscriptions/{subscriptionID}/compatible-plans`.
> 
> **Not idempotent** — see the *Errors* topic before retrying.



## Servers
- Production: https://zim.api.zimconnections.com (Production)
- Sandbox: https://zim.api.dev.zimconnections.com (Sandbox)


## Authentication methods
- Oauth2 & App identifier


## Parameters



### Body: application/json (object)

- **type** (string)

- **planID** (string)

- **accountID** (string)
  Your Account ID. Orders are always created for the caller's Account.

- **currencyISO** (string)
  Ignored: Orders are charged in your Account's billing currency, which `payment.currencyISO` reports.

- **recipientUserNanoIDs** (array[string])
  Users of your Account receiving the plan — one Order per recipient, charged `price × recipients`. Optional for Advance Pay Accounts (defaults to the caller), required for post-paid Accounts. For `TOP_UP`, every recipient must own the Subscription.

- **topUpSubscriptionNanoID** (string)
  Required when `type` is `TOP_UP` — the Subscription to top up

- **notifyRecipient** (boolean)
  If `true`, a notification (push / SMS or email) is sent to the end User based on the Account preferences

- **activationDate** (string)
  Advance Pay Accounts only. Activation date (ISO 8601 or `DD-MM-YYYY`), not in the past.



## Responses
### 201
Order created

#### Body: application/json (object)
- **order** (object)

- **payment** (object)

- **nextAction** (object)


### 400
Invalid request or refused by a business rule

#### Body: application/json (object)
- **statusCode** (integer)

- **message** (string | array[string])
  Human-readable reason, or one entry per invalid property for validation errors

- **error** (string)


### 401
Missing or invalid access token or `X-App-Identifier`

#### Body: application/json (object)
- **statusCode** (integer)

- **message** (string | array[string])
  Human-readable reason, or one entry per invalid property for validation errors

- **error** (string)


### 403
Your role is not allowed to perform this operation

#### Body: application/json (object)
- **statusCode** (integer)

- **message** (string | array[string])
  Human-readable reason, or one entry per invalid property for validation errors

- **error** (string)


### 404
Resource not found or not owned by your Account

#### Body: application/json (object)
- **statusCode** (integer)

- **message** (string | array[string])
  Human-readable reason, or one entry per invalid property for validation errors

- **error** (string)



[Powered by Bump.sh](https://bump.sh)
