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

# Shipments

> The Shipment is Perform.AI's core object — what it contains, how it's identified, and how it comes to life.

A **Shipment** is Perform.AI's virtual representation of a real-world shipment. It links to the physical parcel through a `tracking_number` and a carrier; with both, Perform.AI retrieves tracking events from the carrier's systems and everything else follows — notifications, tracking pages, analytics, webhooks.

## Identifiers

| Identifier                                   | Who sets it | Notes                                                                                                     |
| -------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `shipment_id`                                | You         | Unique across your account; **immutable after creation**. Use a stable ID from your own system.           |
| `shipment_uuid`                              | Perform.AI  | Returned at creation; the canonical reference in every other endpoint.                                    |
| `shipment_reference`, `additional_reference` | You         | Free extra references; searchable in Parcel Overview.                                                     |
| `tracking_number`                            | Carrier     | With the carrier, the link to the physical world. Changeable only while the Shipment has no track events. |

## Open Shipments

A Shipment created **without** a tracking number and carrier is an **Open Shipment** — a standalone record. Two ways it becomes tracked:

* You [update it](/guides/update-shipment) with a `tracking_number` and `carrier_reference` once known.
* You hand it to [Create Booking](/guides/create-booking), which books a carrier and assigns the tracking number for you.

## What a Shipment carries

Beyond identifiers and tracking: **five address roles** (recipient, sender, to, from, return — destination/origin may differ from recipient/sender), the linked **order**, **line items**, monetary values (shipment value, COD, shipping costs), physical attributes (dimensions stored in cm, weight in grams), **documents**, **linked shipments** (other carriers' records of the same physical parcel, whose events merge in), notification recipients, tags, and your own `additional_info` fields. The complete dictionary is the [field reference](/essentials/field-reference).

## Lifecycle

A Shipment's `status` and its current delivery `phase` are separate dimensions — status describes the record's tracking state (`pending`, `active`, `delivered`, `return`…), while phases describe delivery progress (Order events through Delivery). Both are explained in [Statuses and phases](/concepts/statuses-and-phases).

## Working with Shipments

<Columns cols={2}>
  <Card title="Create" href="/guides/create-shipment" icon="plus">
    Only `shipment_id` is required.
  </Card>

  <Card title="Update" href="/guides/update-shipment" icon="pen">
    Replace-vs-append semantics matter.
  </Card>

  <Card title="Search" href="/guides/list-shipments" icon="magnifying-glass">
    Filters, AND/OR syntax, cursor pagination.
  </Card>

  <Card title="Retrieve" href="/guides/retrieve-shipment" icon="box-open">
    The full record with complete event history.
  </Card>
</Columns>