/orders

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
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. Shipments are sent in groups: every group that sets a tourCreationStrategy becomes one tour over its own shipments, and a group without a strategy creates its shipments without a tour, so one request can create several tours. A predefinedLayout counts its shipment indexes within its own group; a layout that does not fit its group's shipments is rejected with 400 wherever it is read, which is when the tour is built and when the order is priced with calculate-fare. An order with status requested and pre-priced line items never reads the layout. With priceStrategy calculate-fare every group is priced on its own, laid out by its own strategy, and the order carries the line items of all groups; a request in which the product prices some groups but not all is rejected with 400. So is a request in which a group's line items do not add up with the other groups' prices, such as a discount or a percentage line, because the order keeps one list of line items and such a line applies to the whole list. 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 shipper that does not exist in the tenant, or a team or user of another shipper, is rejected with 422. Either block may be omitted when the order has a shipper assignment (a shipperId on a shipment group, its shipments or, for the invoice recipient, the customer): the omitted block is filled from the assigned shipper's master data: name, address and contact details of the shipper team (the one sent, or else the shipper user's team) or, without a team, of the shipper, with missing contact details taken from the shipper user. Without an assignment an omitted block is rejected with 400. A shipment group or its shipments may name the assignment with shipperLookup instead of ids: the shipper, shipper team or shipper user that holds a property value, for example a customer number on the team (see the shipperLookup field for the rules and outcomes). It counts as a shipper assignment for omitted blocks, which are then filled from the team or user found. The order and its shipments store the resolved ids; a lookup that names no active holder, or more than one, is rejected with 422, and one that cannot be answered right now with 503.

string

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

string

The customer's own reference number for this order.

string

Customer-facing comment on the order.

string

Operator-only internal comment on the order.

payment
string

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

shipments
array
required

The shipment groups to create under this order. Every group that sets a tourCreationStrategy becomes one tour over its own shipments, laid out by its own predefinedLayout and carrying its own tourDetails; a group without a strategy creates its shipments without a tour. To get one tour per shipment, send one group per shipment. A group that sets a strategy needs at least one shipment.

shipments*
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.

string

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

number

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

lineItems
array of objects
lineItems
string
enum
Allowed:
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
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 one tour for every shipment group that sets a tourCreationStrategy.

Allowed:
customer
object

The booking customer for the order. May be linked to a Shipper via shipperId; that link is the order's shipper assignment. Optional when the order has a shipper assignment (a shipperId or shipperLookup on a shipment group or its shipments): when omitted, it is filled from the assigned shipper's master data, taking name, address and contact details from the shipper team (the shipperTeamId sent, or else the shipper user's team) or, without a team, from the shipper, and missing contact details from the shipper user. Without any assignment it is required (400).

invoiceRecipient
object

The party billed for the order; often the same as customer. May be linked to a Shipper via shipperId, independently of the customer. Optional when the order has a shipper assignment (a shipperId on the customer, or a shipperId or shipperLookup on a shipment group or its shipments): when omitted, it is filled from the assigned shipper exactly like an omitted customer, even when a customer is sent. Without any assignment it is required (400).

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 (a shipperId or shipperLookup on 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

422

the shipper assignment cannot be used: an unknown shipper, a team or user of another shipper, or a shipperLookup that names no active holder or more than one (see the violation codes)

503

the shipper assignment could not be verified right now; nothing was created, retry later

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json