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

​
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 with a tracking_number and carrier_reference once known.
  • You hand it to 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.

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

​
Working with Shipments

Create

Only shipment_id is required.

Update

Replace-vs-append semantics matter.

Search

Filters, AND/OR syntax, cursor pagination.

Retrieve

The full record with complete event history.