Skip to main content
An order in Perform.AI groups multiple shipments and returns under a single identifier for unified visibility. Rather than tracking each parcel in isolation, you can aggregate all outbound shipments and any associated returns under one order, making it easy to monitor the full fulfilment journey from your dashboard or via the API.
Use order_id to group outbound shipments and their returns under the same order. This gives you end-to-end visibility across the entire customer journey — from initial dispatch through to any return — in one place.

​
Key Order Fields

​
How Orders Are Created

Orders cannot exist as standalone objects in Perform.AI — they are always created in the context of a shipment. When you create a shipment and include an order_id, Perform.AI either:
  • Creates a new order with that order_id if no matching order exists, or
  • Assigns the shipment to an existing order if an order with that order_id already exists.
This means you create your order implicitly by including order_id in your first shipment creation request. Subsequent shipments that share the same order_id are automatically grouped under that order.

​
Assigning Shipments to an Existing Order

To add a new shipment to an order that already exists, provide either the order_uuid or the order_id in your shipment creation or update request.
  • order_uuid is preferred when both order_uuid and order_id are provided in the same request — Perform.AI uses order_uuid to resolve the target order.
  • order_id works equally well and is more convenient if you don’t want to store UUIDs in your system.

​
The order_reference Field

order_reference is a secondary human-readable reference for the order (for example, a marketplace order number or ERP reference). It behaves differently from order_id:
  • You can only set order_reference when creating a new order — include it alongside a new order_id in your shipment creation request.
  • If you provide an order_reference for an existing order and the value differs from the one already stored, the API will reject the input.
  • Multiple orders can share the same order_reference value.