Skip to main content
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

A pending Shipment becomes active, delivered, or undeliverable as soon as its first event lands — whether retrieved from the carrier or created manually.

​
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:
Phase keys also appear on each event (phase_key) and power the current_phase filter in 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.
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.
  • 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.