Orders
Mixed orders, order and payment status, and what you can do with an order item after purchase.
Every purchase is an order. An order holds one or more order items, one per product bought, and every product uses the same order envelope.
Placing an order
You can order through a product's own route, such as POST /v1/esims/order, or mix products in one order with POST /v1/orders. POST /v1/orders/quote prices the same mixed body without buying.
{
"currency": "USD",
"referenceId": "my-order-42",
"maxTotal": { "amount": 10.7, "currency": "USD" },
"items": [
{
"productType": "airtime",
"publicId": "airtime_...",
"quantity": 1,
"inputs": { "phoneNumber": "+2348012345678", "value": { "amount": 1000, "currency": "NGN" } }
},
{ "productType": "esim", "publicId": "esim_...", "quantity": 1, "inputs": {} }
]
}- An order has 1 to 5 items, with a total quantity of at most 5. Airtime, utility, eSIM top-ups, hotels and flights take quantity 1.
inputscarries the offer's required inputs plus two standard fields where the product takes them:value(the amount to deliver, for range offers) andmaxPrice(the highest unit price you accept).maxTotal(mixed orders only) is the highest order total you accept. A higher total is409 / 11002and nothing is charged.referenceIdis your own reference, kept with the order.- Every order needs an
Idempotency-Key. See Idempotency.
OpenRoam charges the order total to your wallet when it accepts the order. A refused charge is 402 / 16000 and keeps no order.
Reading orders
GET /v1/orders/{id}returns one order as it is now.GET /v1/orderslists orders, with filters andpageandlimitpaging.GET /v1/orders/{orderId}/fulfillment/statusreturns the delivery state of every item.
An order of another account answers 404 / 10004, exactly like an unknown id.
Order status
status | Meaning |
|---|---|
paymentPending | The order exists and its payment has not completed. Rare on the API: if a wallet charge was taken but not confirmed, repeating the order request with the same key completes it, and OpenRoam completes it automatically too. The wallet is never charged twice |
processing | Paid, and at least one item has no outcome yet |
completed | Every item was delivered |
partiallyFulfilled | Some items were delivered and the others were rejected and refunded |
fulfillmentFailed | No item was delivered. Rejected items are refunded |
partiallyRefunded | At least one delivered item was cancelled and refunded, and at least one was not |
refunded | Every delivered item was cancelled and refunded |
cancelled | The order was never paid; nothing was charged |
payment.status is pending, authorized, completed, failed, partiallyRefunded, refunded or cancelled. total is what was charged, and refunded is what completed refunds returned.
Order items
Each item carries:
purchasedProduct: what was bought, with the inputs you sent. Customer identifiers are masked: phones as+<country code>***<last 4>, emails asa***@domain, other identifiers as***<last 4>.fulfillment:status(pending,fulfilledorrejected),result(only what was delivered, such as a gift card code or a hotel confirmation) andfailure. While an outcome is being confirmed, a pending item can also carryprogresswith the codeCONFIRMING_OUTCOME.actions: whether you can cancel, amend or update the item now.refund: the item's refund, once there is one.
A rejected item is refunded automatically and reported by the order-item.refunded webhook. There is no retry: to deliver it again, place a new order.
After purchase
All products share the same item routes. The item id is items[].id from the order.
| Operation | Route | Permission | Idempotency-Key |
|---|---|---|---|
| Get an item | GET /v1/order-items/{id} | read | no |
| Preview a cancellation | GET /v1/order-items/{id}/cancellation-preview | read | no |
| Preview cancelling a whole order | GET /v1/orders/{id}/cancellation-preview | read | no |
| Cancel | POST /v1/order-items/{id}/cancel | manage | yes |
| Update | POST /v1/order-items/{id}/update | manage | yes |
| Quote an amendment | POST /v1/order-items/{id}/amendments/quote | manage | yes |
| Confirm an amendment | POST /v1/order-items/{id}/amendments/confirm | manage | yes |
| List an item's amendments | GET /v1/order-items/{id}/amendments | read | no |
| List all amendments | GET /v1/amendments | read | no |
| Hotel manual amendments | POST /v1/order-items/{id}/manual-amendments and its approve, decline and cancel routes | manage | create and approve |
Check the item's actions first. Each of actions.cancellation, actions.amendment and actions.update has an availability and a reason. A call that is not available now is refused with a 409 from the 18001-18005 range; a kind of item that can never do it gives a 422. See Errors.
What each product supports:
| Product | Cancel | Amend | Update |
|---|---|---|---|
| Airtime, utility, eSIMs | Not after delivery (422 / 18000). A rejected item is refunded automatically | no | no |
| Gift cards | Not after delivery (422 / 18000). A rejected item is refunded automatically | no | The gift recipient and message |
| Hotels | By the cancellation terms of the booking | By API for some hotels, otherwise with manual amendments | no |
| Flights | By the rules of the fare | By API | no |
The product guides explain the details: Gift cards, Hotels and Flights.
Resend a traveller email
For an order placed on one of your hosted sites, POST /v1/orders/{id}/emails/resend sends the receipt, or one item's delivery email, to the traveller again.