Skip to Content
OpenRoam Docs

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.

POST /v1/orders
{
  "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.
  • inputs carries the offer's required inputs plus two standard fields where the product takes them: value (the amount to deliver, for range offers) and maxPrice (the highest unit price you accept).
  • maxTotal (mixed orders only) is the highest order total you accept. A higher total is 409 / 11002 and nothing is charged.
  • referenceId is 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

An order of another account answers 404 / 10004, exactly like an unknown id.

Order status

statusMeaning
paymentPendingThe 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
processingPaid, and at least one item has no outcome yet
completedEvery item was delivered
partiallyFulfilledSome items were delivered and the others were rejected and refunded
fulfillmentFailedNo item was delivered. Rejected items are refunded
partiallyRefundedAt least one delivered item was cancelled and refunded, and at least one was not
refundedEvery delivered item was cancelled and refunded
cancelledThe 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 as a***@domain, other identifiers as ***<last 4>.
  • fulfillment: status (pending, fulfilled or rejected), result (only what was delivered, such as a gift card code or a hotel confirmation) and failure. While an outcome is being confirmed, a pending item can also carry progress with the code CONFIRMING_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.

OperationRoutePermissionIdempotency-Key
Get an itemGET /v1/order-items/{id}readno
Preview a cancellationGET /v1/order-items/{id}/cancellation-previewreadno
Preview cancelling a whole orderGET /v1/orders/{id}/cancellation-previewreadno
CancelPOST /v1/order-items/{id}/cancelmanageyes
UpdatePOST /v1/order-items/{id}/updatemanageyes
Quote an amendmentPOST /v1/order-items/{id}/amendments/quotemanageyes
Confirm an amendmentPOST /v1/order-items/{id}/amendments/confirmmanageyes
List an item's amendmentsGET /v1/order-items/{id}/amendmentsreadno
List all amendmentsGET /v1/amendmentsreadno
Hotel manual amendmentsPOST /v1/order-items/{id}/manual-amendments and its approve, decline and cancel routesmanagecreate 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:

ProductCancelAmendUpdate
Airtime, utility, eSIMsNot after delivery (422 / 18000). A rejected item is refunded automaticallynono
Gift cardsNot after delivery (422 / 18000). A rejected item is refunded automaticallynoThe gift recipient and message
HotelsBy the cancellation terms of the bookingBy API for some hotels, otherwise with manual amendmentsno
FlightsBy the rules of the fareBy APIno

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.

On this page