# Orders (/docs/orders)

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 [#placing-an-order]

You can order through a product's own route, such as [`POST /v1/esims/order`](/docs/api-reference/esims/create-order), or mix products in one order with [`POST /v1/orders`](/docs/api-reference/orders/create-order). [`POST /v1/orders/quote`](/docs/api-reference/orders/quote-order) prices the same mixed body without buying.

```json title="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](/docs/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 [#reading-orders]

- [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id) returns one order as it is now.
- [`GET /v1/orders`](/docs/api-reference/orders/get-all) lists orders, with filters and `page` and `limit` paging.
- [`GET /v1/orders/{orderId}/fulfillment/status`](/docs/api-reference/orders/get-fulfillment-status) returns the delivery state of every item.

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

## Order status [#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 [#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 [#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}`](/docs/api-reference/order-items/get-by-id) | `read` | no |
| Preview a cancellation | [`GET /v1/order-items/{id}/cancellation-preview`](/docs/api-reference/order-items/get-cancellation-preview) | `read` | no |
| Preview cancelling a whole order | [`GET /v1/orders/{id}/cancellation-preview`](/docs/api-reference/orders/get-cancellation-preview) | `read` | no |
| Cancel | [`POST /v1/order-items/{id}/cancel`](/docs/api-reference/order-items/cancel) | `manage` | yes |
| Update | [`POST /v1/order-items/{id}/update`](/docs/api-reference/order-items/update) | `manage` | yes |
| Quote an amendment | [`POST /v1/order-items/{id}/amendments/quote`](/docs/api-reference/order-items/quote-amendment) | `manage` | yes |
| Confirm an amendment | [`POST /v1/order-items/{id}/amendments/confirm`](/docs/api-reference/order-items/confirm-amendment) | `manage` | yes |
| List an item's amendments | [`GET /v1/order-items/{id}/amendments`](/docs/api-reference/order-items/get-amendments) | `read` | no |
| List all amendments | [`GET /v1/amendments`](/docs/api-reference/order-items/list-partner-amendments) | `read` | no |
| Hotel manual amendments | [`POST /v1/order-items/{id}/manual-amendments`](/docs/api-reference/hotel-manual-amendments/create-manual-amendment) 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](/docs/errors#after-purchase).

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](/docs/products/gift-cards), [Hotels](/docs/products/hotels) and [Flights](/docs/products/flights).

## Resend a traveller email [#resend-a-traveller-email]

For an order placed on one of your hosted sites, [`POST /v1/orders/{id}/emails/resend`](/docs/api-reference/orders/resend-email) sends the receipt, or one item's delivery email, to the traveller again.