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

# Statuses and phases

> The two dimensions of a Shipment's lifecycle — record status and delivery phase — and how to use each.

Two fields describe where a Shipment stands, and they answer different questions:

* **`status`** — the state of the Shipment *record*: is Perform.AI tracking it, and how did tracking end?
* **`current_phase`** — the stage of the *delivery journey* the latest event maps to.

Use `status` for record-keeping logic (is this done? did tracking ever start?), and phases for customer-facing journey displays and milestone logic.

## Statuses

| Status      | Meaning                                                               |
| ----------- | --------------------------------------------------------------------- |
| `pending`   | Created, no events yet — including Open Shipments awaiting a carrier. |
| `active`    | Tracking events are flowing; the delivery is in progress.             |
| `delivered` | The carrier delivered the shipment.                                   |
| `inactive`  | Tracking stopped without a delivered outcome.                         |
| `expired`   | No conclusive events arrived within the tracking window.              |
| `return`    | The Shipment is a Return (or was returned).                           |

A `pending` Shipment becomes `active`, `delivered`, or undeliverable as soon as its first event lands — whether retrieved from the carrier or [created manually](/guides/create-events).

## Phases

Every event is mapped, where possible, to a standard **phase** of the delivery journey — from order events through handover, transit, customs, out-for-delivery, and delivery. Each phase has a display `name` and a stable `key` (for example `G` — Out for delivery, `H` — Delivery); the Shipment's `current_phase` reflects its most recent mapped event:

```json theme={null}
"current_phase": { "name": "Out for delivery", "key": "G" }
```

Phase keys also appear on each event (`phase_key`) and power the `current_phase` filter in [List Shipments](/guides/list-shipments). Events that can't be mapped carry `null` phase fields — your logic should treat unmapped events as "no phase information", not as an error.

<Note>
  Build logic on the **keys**, not the display names — names can be reworded; keys are stable. Resolve human terms to keys with the List Event Types API or ask your account team for the full standard event and phase catalogue.
</Note>

## Related dimensions

* **`issue_state`** (`no_issue` / `current_issue` / `past_issue`) tracks whether the Shipment has hit delivery issues — a separate axis from status and phase.
* **Return Shipments** additionally carry a `return_status` lifecycle (pending approval → approved → shipping → completed, among others) — see [Returns](/concepts/returns).