Skip to main content

Orders and Shipments

Order is the public root resource​

An Order is the public resource created through V1 creation or Create an Order with Rates. Retain the orderId: it is used to list Orders, get an Order, and update Order status.

Why the API is order-first​

Every workflow in this API starts by creating an Order. There is no operation that creates a Shipment, a Parcel, or an Address on its own, and no operation that rates or labels anything that does not already belong to an Order. That is a property of the published surface, not a convention you can route around:

Order  ->  Shipment  ->  Rates  ->  Label

Two consequences follow from it, and they are the practical reason to know the shape:

  • An Order is the unit of identity. shipmentId, rateId and labelId are all reachable from an orderId, so getting the Order is how you recover the state of anything underneath it. This is what makes recovery after a lost response possible without a separate lookup operation per resource — see Retries and Ambiguous Outcomes.
  • Addresses and parcels are Order data, not standalone resources. They are supplied inside the create-Order request and echoed back on the Order; there is no address book or parcel catalogue to populate first, and nothing to keep in sync.

Model your integration the same way: create the Order when you have a fulfilment decision to record, keep the identifiers it returns, and drive rating and labelling from those. Building a client that holds shipments outside an Order will not map onto any operation this API publishes.

Shipment belongs to an Order​

A Shipment is created as part of an Order. Retain each shipmentId: it is the identifier used to get Rates and create a Label. The Shipment uses the Order's embedded Address and Parcel data.

Shipment processing or status is distinct from Order fulfilment status. Do not infer Order fulfilment from a Shipment status; use the Order status when you need the Order's fulfilment progress.

Get Order projects one Shipment​

An Order can contain one or more Shipments, but the Get Order response is a projection: it returns a single shipment object — the most recently created Shipment of that Order, not the most recently updated one — and the shipmentId and labelId alongside it refer to that same Shipment and its most recent Label.

This is a response shape, not a change to the model: the Order still holds every Shipment it was created with. Retain every shipmentId that Order creation returned rather than expecting to recover them all from a later read, and use each one directly for Rates and Label purchase. An Order with no Shipment yet returns none.

Two creation choices​

Standard Order creation creates one Order without requesting Rates during creation. Create an Order with Rates uses the same creation path, then adds immediate Rate retrieval for each created Shipment in that one Order. Its shipmentRates response groups results by Shipment, not by Order. It is a combined create-and-rate flow, not a replacement for the standard flow.

Identifier flow​

create Order
  -> retain orderId
  -> retain shipmentId
  -> use shipmentId for Rates
  -> use a selected rateId for Label purchase
  -> retain labelId

Continue with the workflows​