> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders: Group and Track Shipments in Perform.AI

> An order groups multiple shipments and returns under one identifier in Perform.AI, giving you unified end-to-end visibility across your fulfilment.

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.

<Info>
  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.
</Info>

## Key Order Fields

| Field               | Set by     | Description                                                                                                                                                                                              |
| ------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_id`          | You        | Your user-defined unique identifier for the order (e.g. `ORD-20240101-001`). Max 50 characters. Accepts letters (A–Z, a–z), digits (0–9), underscores (`_`), dashes (`-`), and periods (`.`). No spaces. |
| `order_uuid`        | Perform.AI | System-generated UUID assigned when the order is first created. Use this in subsequent API calls to reference the order.                                                                                 |
| `order_reference`   | You        | A secondary reference for the order (e.g. a marketplace or ERP reference). Multiple orders can share the same `order_reference`.                                                                         |
| `order_source_type` | You        | The type of system that originated the order (e.g. `OMS`, `webshop`). Used for filtering in the Parcel Overview.                                                                                         |
| `order_source_name` | You        | The name of the specific source system (e.g. `RetailSystemV1`).                                                                                                                                          |

## 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.

```json theme={null}
{
  "shipment_id": "SHIP-001",
  "tracking_number": "1Z999AA10123456784",
  "carrier_reference": "ups-outbound",
  "order_id": "ORD-20240101-001",
  "order_source_type": "OMS",
  "order_source_name": "RetailSystemV1"
}
```

## 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.

```json theme={null}
{
  "shipment_id": "SHIP-002",
  "tracking_number": "1Z999AA10123456785",
  "carrier_reference": "ups-outbound",
  "order_uuid": "3b9b7d28-79e0-4d8b-800a-28d5b739540a"
}
```

## 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.

```json theme={null}
{
  "shipment_id": "SHIP-003",
  "tracking_number": "1Z999AA10123456786",
  "carrier_reference": "ups-outbound",
  "order_id": "ORD-20240102-001",
  "order_reference": "MKT-REF-9901"
}
```