/orders

post

https://api.dev.orbit.do/v5/orders

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request to create an order, one or more shipments and optionally tours. Order can be priced automatically or pre-priced and may require payment info to be processed. Set matchShipperAddresses to true to match each stop against the assigned shipper's saved address book. Saved-address references sent on a stop (shipperAddressId, shipperAddressContactId, shipperAddressLoadingPoint) are always checked against the assigned shipper: with matchShipperAddresses true a reference that does not belong to that shipper is rejected with 400, otherwise it is removed and the order is created without it. For an order with status requested the flag applies the reference validation only; the stored shipment requests are not matched when the order is confirmed later. customer and invoiceRecipient may each be linked to a shipper via shipperId (narrowed by shipperTeamId / shipperUserId): the customer's link is the order's shipper assignment and must agree with the shipment groups, the invoice recipient may name a different shipper; a team or user of another shipper is rejected with 422.

displayName

string

Optional human-facing label for the order; the internal id is generated regardless.

customerReference

string

The customer's own reference number for this order.

customerComment

string

Customer-facing comment on the order.

internalComment

string

Operator-only internal comment on the order.

payment

voucherCode

string

A voucher/discount code to apply to the order's pricing, if any.

shipments

array

required

The shipment groups (with their tour-creation layout) to create under this order.

shipments*

session

string

properties

object

Key-value pairs in the dictionary have property IDs as keys. Property keys and their values appear only when the property value is explicitly set. All property values are validated against their definitions - requests with unknown property IDs or invalid value types will be rejected with a 400 error.

productId

string

Internal Product id (UUID) to price this order against.

productValidAt

number

Epoch-seconds timestamp at which to evaluate the product's pricing, pinning the pricing version.

lineItems

array of objects

lineItems

brickMessages

array of objects

brickMessages

metrics

array of objects

metrics

priceStrategy

required

How the order is priced: calculate-fare prices it from a Product, pre-priced accepts caller-supplied line items verbatim.

transactions

array of objects

Payments already captured outside Orbit, recorded against the order by provider transaction/payment-intent id. Cannot be combined with payment: send payment to settle the order now, or transactions to record payments captured elsewhere, but not both. A request carrying both is rejected with 400.

transactions

status

string

enum

required

The initial order status to record (external callers set this explicitly rather than having it derived). requested stores the shipment groups as shipmentRequests only and creates no shipments or tour; confirmed books the order now, building its shipments and (when the first shipment group asks for one) its tour.

Allowed:

customer

object

required

The booking customer for the order. May be linked to a Shipper via shipperId; that link is the order's shipper assignment.

invoiceRecipient

object

required

The party billed for the order; often the same as customer. May be linked to a Shipper via shipperId, independently of the customer.

matchShipperAddresses

boolean

When true (here or on any shipment group), every stop address of the order is matched against the assigned shipper's saved address book: a match overwrites the address fields with the saved values and fills in shipperAddressId, opening hours, properties and a matching contact, while an unmatched stop is stored as sent. Defaults to false and requires a shipper assignment somewhere in the order (any shipment group or, uniformly, its shipments); a stop already carrying a valid shipperAddressId is left as sent. Saved-address references are always validated: with matching enabled an unknown reference is rejected with status 400, otherwise it is removed and the order is still created; for an order with status requested the flag applies this validation only, and the stored shipment requests are not matched when the order is confirmed later (see the endpoint description).

Responses

400

bad request

401

unauthorized

Language

Credentials

Header

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200created order and optionally created shipments and tours