Purchase orders and order lines
A purchase order is one commercial transaction on a trip, placed on one channel at one purchase moment. The booking made on the web is one purchase order; the excursions added later in the mobile app are another; a drinks package bought onboard is a third. Each keeps its own channel, booker, payer, terms and history, and they all sum into the trip.
Creating purchase orders
| How | Call | Use |
|---|---|---|
| Convert a quotation | POST /order-orchestration/quotations/{ref}/convert | The booking itself, from an accepted quote. |
| Hand over frozen conditions | POST /order-orchestration/trips/{tripId}/handover | An accepted quote sold into an existing trip without a tracked quotation (for example an add-on priced in the quote store). Idempotent per quote reference and version. |
| Create directly | POST /order-orchestration/trips/{tripId}/purchase-orders | Lines priced by the channel itself, for example an add-on bought in the mobile app. |
The channel, moment and market must be codes from the orchestration configuration. Product types that the configuration restricts to certain channels (line_availability) are refused elsewhere with 422 not_available_on_channel.
| Field | Meaning |
|---|---|
sequence | 1 for the first order on the trip, then 2, 3… |
channel, moment, market | Where and when it was sold. |
booker, payer | Parties { kind, ref, displayName } with kind customer, agency, agent or company. Locked once the order is booked (partiesLocked). |
origin, finalisation | The channel and touchpoint it started on, and where it was finalised. |
attribution | agencyRef and campaignRef. |
terms | Selling conditions: refundable, cancellationPolicyId, depositPercent, balanceDueAt. |
frozenConditions | For converted and handed-over orders: the quote reference and version, the configuration and price-store versions, and the full frozen document. |
revisions | Every order change applied, with old and new amounts. |
version | Increases on every change; use it with If-Match. |
Order lines
Each line is one product: productType, productCode, quantity, amountMinor, passengerIds, serviceDate, offers and promotions, and the price explanation from the quote.
When a line is created, the execution-ownership rules choose the system that executes it. The line records the result in sourceSystem and ownership ({ process, ruleId }), and the order engine sends that system a create request. In the end-to-end example the cabin goes to the reservation system, the drinks package to the onboard account and the excursions to the excursion system.
Order lines are also projected to order operations (GET /oms-ops/trips/{tripId}/lines), where payments are allocated to them.
Statuses
Purchase orders and lines carry four independent status dimensions. The commercial status of an order is changed by a user action; the other dimensions, and line statuses, move with the status events that specialist systems send (see the event catalogue).
trip
| Dimension | Values (terminal values in bold) |
|---|---|
| lifecycle | lead, quotation, option, booked, closed |
purchase order
| Dimension | Values (terminal values in bold) |
|---|---|
| commercial | quotation, option, booked, cancelled, frozen, closed |
| payment | not_due, pending, authorised, partially_paid, paid, refunded, failed |
| fulfilment | not_started, requested, confirmed, fulfilled, not_fulfilled, cancelled |
| billing | not_billed, invoiced, credited, closed |
order line
| Dimension | Values (terminal values in bold) |
|---|---|
| commercial | quotation, option, booked, cancelled, frozen, closed |
| payment | not_due, pending, authorised, partially_paid, paid, refunded, failed |
| fulfilment | not_started, requested, confirmed, fulfilled, not_fulfilled, cancelled |
| billing | not_billed, invoiced, credited, closed |
Commercial transitions requested with POST /purchase-orders/{poId}/transition:
| From | To |
|---|---|
quotation, option | booked, cancelled |
booked | cancelled, frozen, closed |
frozen | booked, cancelled, closed |
cancelled, closed | none (terminal) |
Any other transition is refused with 409 invalid_transition. frozen holds an order (for example for a payment review) without cancelling it.
Changing a purchase order
| Change | Call |
|---|---|
| Reprice after a booking change (cabin, fare, sailing) | POST /purchase-orders/{poId}/changes with a repricing proposal or the id of a confirmed one from the repricing service. Each promotion follows its post-booking policy. |
| Remove passengers, cancel a cabin, cancel the whole order | POST /oms-ops/changes; see Changes and refunds. |
| Cancel, freeze or close | POST /purchase-orders/{poId}/transition. |
Each order change is a revision on the order; the owning systems receive modify (or cancel) requests.
See the reference for Purchase orders and Order lines.