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 × recipientsis refused withINSUFFICIENT_BALANCEand nothing is created; there is no card fallback. Defaults to the caller as recipient. - Post-paid - billed on your monthly post-paid invoice.
recipientUserNanoIDsis 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.
Body
Required
-
Values are
ONE_OFForTOP_UP. -
Your Account ID. Orders are always created for the caller's Account.
-
Ignored: Orders are charged in your Account's billing currency, which
payment.currencyISOreports. -
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. ForTOP_UP, every recipient must own the Subscription.Not more than
50elements. Maximum length of each is32. -
Required when
typeisTOP_UP— the Subscription to top up -
If
true, a notification (push / SMS or email) is sent to the end User based on the Account preferencesDefault value is
true. -
Advance Pay Accounts only. Activation date (ISO 8601 or
DD-MM-YYYY), not in the past.
curl \
--request POST 'https://zim.api.zimconnections.com/v2/orders' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "X-App-Identifier: $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"type": "ONE_OFF",
"planID": "plan_guaGulGcrqgTYboPvetgu",
"accountID": "acct_ozxEbkTyvLPhhoglcALXE",
"currencyISO": "usd",
"recipientUserNanoIDs": [
"user_yf95A86RIkVxau2gzBsjV",
"user_ozxEbkTyvLPhhoglcALXR"
]
}'
{
"type": "ONE_OFF",
"planID": "plan_guaGulGcrqgTYboPvetgu",
"accountID": "acct_ozxEbkTyvLPhhoglcALXE",
"currencyISO": "usd",
"recipientUserNanoIDs": [
"user_yf95A86RIkVxau2gzBsjV",
"user_ozxEbkTyvLPhhoglcALXR"
]
}
{
"type": "TOP_UP",
"planID": "plan_guaGulGcrqgTYboPveAAB",
"accountID": "acct_ozxEbkTyvLPhhoglcALXE",
"topUpSubscriptionNanoID": "subs_BiPtvfzYKwcyNMNvTGmLO",
"recipientUserNanoIDs": [
"user_yf95A86RIkVxau2gzBsjV"
]
}
{
"order": {
"id": "ordr_GMAVA4ISiqfWSG0ArGOzB",
"accountID": "acct_ozxEbkTyvLPhhoglcALXE",
"planID": "plan_guaGulGcrqgTYboPvetgu",
"userID": "user_yf95A86RIkVxau2gzBsjV",
"createdAt": "2026-10-27T14:39:23.149Z",
"status": "PROCESSING",
"type": "ONE_OFF"
},
"payment": {
"paymentNanoID": "paym_4FzTYboPvetguABCDEFG",
"status": "RECEIVED",
"amount": 2980,
"currencyISO": "usd"
},
"nextAction": {
"type": "none"
}
}
{
"statusCode": 400,
"message": [
"property foo should not exist"
],
"error": "Bad Request"
}
{
"statusCode": 401,
"message": "Unauthorized"
}
{
"statusCode": 403,
"message": "Forbidden resource",
"error": "Forbidden"
}
{
"statusCode": 404,
"message": "Record not found",
"error": "Not Found"
}