The Shipment object

Every field of the Shipment object, its enums, and the rules for nulls, dates and units.

GET /v1/shipments and GET /v1/shipments/{reference} return the same object. The OpenAPI document is the authoritative schema.

Rules

Every key is always present. An unknown value is null; an empty list is [].
null means "not known yet" or "does not apply to this shipment"; it is never an error. A value that is null today can be filled in tomorrow.
Milestone dates are local calendar dates: yyyy-MM-dd, local to the place, with an optional local HH:mm. No time zone; do not convert them. They sort correctly as text.
Timestamps (createdAt, updatedAt, cancelledAt) are ISO 8601 in UTC.
Units are as recorded, not normalised. A weight is { "value": 1082, "unit": "KG" } on one shipment and { "value": 7600, "unit": "LB" } on another, and units can differ within one shipment.
Enum values are case-sensitive. Match them exactly.

Annotated example

An ocean DDP shipment, abridged. Complete examples are on Shipment types.

JSON

{
  "reference": "QB10293",
  "status": "Active",                 // Active | Delivered | Cancelled
  "serviceType": "OceanDDP",
  "mode": "Ocean",                    // Ocean | Air | Land
  "incoterms": "EXW",                 // who arranges origin pickup; FOB | EXW | null
  "tags": ["PO-8841"],                // the customer's own PO numbers
  "descriptionOfGoods": "Yoga mats",
  "insured": true,
  "bookingConfirmedByCarrier": true,

  "origin":          { "name": "Shenzhen Lotus Sports Goods Co., Ltd.", "type": "ShippingParty", "city": "Shenzhen", "countryCode": "CN", "code": null, /* … */ },
  "portOfLoading":   { "name": "Yantian", "type": "Seaport", "code": "CNYTN", "countryCode": "CN", /* … */ },
  "portOfDischarge": { "name": "Long Beach", "type": "Seaport", "code": "USLGB", "countryCode": "US", /* … */ },   // can be null
  "destination":     { "name": "ONT8", "type": "FulfillmentCenter", "fulfillmentCenter": "Amazon", "countryCode": "US", /* … */ },

  "carrier": { "name": "COSCO", "type": "ShippingLine" },   // null for land
  "booking": {
    "bookingNumber": null,
    "masterBill": "COSU6412345670",   // ocean master B/L, or air MAWB
    "houseBill": "SZX2607001",        // ocean house B/L, or air HAWB
    "cargoCutoff": "2026-07-05",
    "shippingInstructionCutoff": null,
    "destinationPortFreeDays": null,
    "emptyContainerReturnFreeDays": null
  },
  "parcels": { "carrier": "UPS", "trackingNumbers": ["1Z84R2E70312345678"] },   // null when none
  "amazon":  { "fbaIds": ["FBA18K4TQ9ZB"], "referenceIds": ["7KQ2M9XA"] },       // null when none

  "cargo": {
    "totalWeight": { "value": 1082, "unit": "KG" },
    "totalVolume": { "value": 6.486, "unit": "CubicMeter" },
    "chargeableWeight": null,         // air and courier only
    "stackable": null,
    "containers": [{ "number": "CSNU1234567", "type": "FortyFtHighCube", "sealNumber": "CN8812045" }],   // shared container on LCL/DDP/DDU
    "packages": [{ "type": "Box", "quantity": 62, "hazardous": false,
                   "weight": { "value": 17.45, "unit": "KG" },        // per package, not per line
                   "length": { "value": 48, "unit": "Centimeter" }, "width": { /* … */ }, "height": { /* … */ } }]
  },

  "milestones": [
    { "type": "Pickup", "place": { /* … */ }, "warehouseType": null, "cargoReadyDate": "2026-07-03",
      "arrival": null,
      "departure": { "date": "2026-07-03", "time": null, "actual": true },
      "completed": true,
      "transportToNext": { "mode": "Truck", "vessel": null, "voyageNumber": null, "flightNumber": null, "carrier": null } },
    { "type": "IntermediaryWarehouse", "warehouseType": "ConsolidationWarehouse", "place": null /* always null */, /* … */ },
    { "type": "OriginPort", /* … */ "transportToNext": { "mode": "Voyage", "vessel": "COSCO SHIPPING ANDES", "voyageNumber": "027E", /* … */ } },
    { "type": "DestinationPort", "arrival": { "date": "2026-07-28", "time": "08:00", "actual": true }, /* … */ },
    { "type": "IntermediaryWarehouse", "warehouseType": "DeconsolidationWarehouse", "place": null, /* … */ },
    { "type": "Delivery", "arrival": { "date": "2026-08-04", "time": null, "actual": false } /* estimate */, "transportToNext": null }
  ],

  "currentMilestoneIndex": 3,         // the DestinationPort milestone: the last one completed
  "cancelledAt": null,
  "createdAt": "2026-06-28T10:12:00Z",
  "updatedAt": "2026-07-29T06:40:00Z"
}

Shipment

Field	Type	Description
`reference`	string	Cubic reference. Unique, stable, and the identifier used in `GET /shipments/{reference}`.
`status`	string	Derived status; the first matching rule wins. `Cancelled`: `cancelledAt` is set. `Delivered`: the `Delivery` milestone has an actual arrival. `Active`: everything else. For where an active shipment is, read `currentMilestoneIndex` and `milestones`. Values: `Active`, `Delivered`, `Cancelled`.
`serviceType`	string	The service booked. `Express` variants have the same shape as their base type. `DDP`/`DDU` are door-to-door services with duties paid/unpaid. `LandTruck` is a legacy value found only on historical shipments; new land shipments use `LandTruckFTL` or `LandTruckLTL`. Values: `OceanFCL`, `OceanFCLExpress`, `OceanLCL`, `OceanLCLExpress`, `OceanDDU`, `OceanDDP`, `AirFreight`, `AirCourier`, `AirDDU`, `AirDDP`, `LandTruckFTL`, `LandTruckLTL`, `LandRailFCL`, `LandRailLCL`, `LandTruck`.
`mode`	string	Transport mode of the main leg, implied by `serviceType`. Values: `Ocean`, `Air`, `Land`.
`incoterms`	string \| null	Who arranges the origin pickup. `EXW`: Cubic collects the cargo from the supplier. `FOB`: the supplier delivers the cargo to the port of loading. It says nothing about duties or door delivery, and it coexists with a DDP/DDU `serviceType`. `null` when not recorded. Values: `FOB`, `EXW`.
`tags`	string[]	The customer's own tags on the shipment — in practice purchase order numbers. Filter on one with the `tag` query parameter. Empty when none.
`descriptionOfGoods`	string \| null	Free-text description of the goods.
`insured`	boolean	Whether the shipment is insured.
`bookingConfirmedByCarrier`	boolean	Whether the carrier has confirmed the booking.
`origin`	Place \| null	Where the cargo is collected.
`portOfLoading`	Place \| null	Port of loading: the seaport or airport where the main leg starts. `null` when the route has no port (for example land shipments, or courier shipments that list only pickup and delivery).
`portOfDischarge`	Place \| null	Port of discharge: the seaport or airport where the main leg ends. Some routes have no `DestinationPort` milestone; then this is the `Delivery` milestone's place if that is a port (door-to-port shipments), otherwise `null`. Never assume it is set.
`destination`	Place \| null	Where the cargo is delivered. May itself be a port (door-to-port), an Amazon fulfilment centre, or an address.
`carrier`	Carrier \| null	The main carrier: the shipping line for ocean, the airline for air, the courier company for `AirCourier`. Always `null` for land shipments, and `null` on other shipments until known. Individual legs carry their own `carrier` in `milestones[].transportToNext`.
`booking`	Booking	Booking and bill-of-lading details. The object is always present; land and courier shipments usually have every member `null`. `null` means "not known yet" or "does not apply to this shipment"; it is never an error. A value that is not known yet can appear on a later read.
`parcels`	Parcels \| null	Last-mile parcel tracking. `null` when there is none. Present on courier shipments and on many DDP/DDU shipments.
`amazon`	Amazon \| null	Amazon inbound identifiers. `null` when there are none.
`cargo`	Cargo	What is being shipped. The object is always present. Units vary between shipments and even between members of one shipment; convert yourself if you need a single unit.
`milestones`	Milestone[]	The route, in order, from `Pickup` to `Delivery`. The milestone types present vary by shipment: never look a milestone up by index, and never assume a given type exists (some routes have no `DestinationPort`, courier shipments may have only `Pickup` and `Delivery`).
`currentMilestoneIndex`	integer	Index in `milestones` of the last milestone with `completed: true` — where the shipment is, or the milestone it last left. `0` when no milestone is completed yet. The shipment is on its way to the next milestone once this one has an actual `departure`.
`cancelledAt`	string \| null	When the shipment was cancelled. ISO 8601, UTC. `null` unless cancelled.
`createdAt`	string	When the shipment was created. ISO 8601, UTC.
`updatedAt`	string	When anything on the shipment last changed. ISO 8601, UTC. The list is sorted by this, newest first; store the greatest value seen and pass it as `updatedSince` to poll for changes.

Place

Field	Type	Description
`name`	string \| null	Display name: the company or site name for a `ShippingParty`, the port or airport name for ports, the fulfilment centre code (for example `ONT8`) for a `FulfillmentCenter`.
`type`	string	Kind of place. `ShippingParty` is a supplier, consignee or warehouse address; `ManualAddress` is a free-typed address. Values: `ShippingParty`, `FulfillmentCenter`, `Seaport`, `Airport`, `InlandTerminal`, `ManualAddress`.
`city`	string \| null	City.
`state`	string \| null	State, province or region, where the country uses one.
`countryCode`	string \| null	ISO 3166-1 alpha-2 country code.
`code`	string \| null	UN/LOCODE for a `Seaport` or `InlandTerminal` (for example `USLGB`), IATA code for an `Airport` (for example `ORD`). `null` for every other type.
`fulfillmentCenter`	string \| null	The fulfilment network the place belongs to (for example `Amazon`) when `type` is `FulfillmentCenter`; otherwise `null`.
`coordinates`	Coordinates \| null	Where the place is on the map, or `null` when not known.

Coordinates

Field	Type	Description
`lat`	number	Latitude.
`lon`	number	Longitude.

Carrier

Field	Type	Description
`name`	string	Carrier name.
`type`	string	Kind of carrier. Values: `ShippingLine`, `Airline`, `Courier`.

Booking

Field	Type	Description
`bookingNumber`	string \| null	The carrier's booking number. Often `null` even on ocean shipments.
`masterBill`	string \| null	Master bill number: the ocean master bill of lading (MBL) or the air master air waybill (MAWB). Searchable with `search`.
`houseBill`	string \| null	House bill number: the ocean house bill of lading (HBL) or the air house air waybill (HAWB).
`cargoCutoff`	string \| null	Latest date the cargo can be delivered to the port or terminal for the booked departure. Local calendar date at the place it refers to, `yyyy-MM-dd`. It has no time zone; do not convert it.
`shippingInstructionCutoff`	string \| null	Latest date the shipping instructions can be submitted to the carrier. Local calendar date at the place it refers to, `yyyy-MM-dd`. It has no time zone; do not convert it.
`destinationPortFreeDays`	integer \| null	Free days at the port of discharge before storage/demurrage charges start.
`emptyContainerReturnFreeDays`	integer \| null	Free days to return the empty container before detention charges start.

Parcels

Field	Type	Description
`carrier`	string \| null	The parcel carrier. Known values: `UPS`, `FedEx`, `DHL`, `TNT`, `DPD_UK`, `DPD_DE`. This is an open set — new values can appear without notice, so do not reject unknown ones.
`trackingNumbers`	string[]	The parcel carrier's tracking numbers.

Amazon

Field	Type	Description
`fbaIds`	string[]	Amazon FBA shipment IDs.
`referenceIds`	string[]	Amazon reference IDs.

Cargo

Field	Type	Description
`totalWeight`	Weight \| null	Total gross weight of the shipment.
`totalVolume`	Volume \| null	Total volume of the shipment.
`chargeableWeight`	Weight \| null	Chargeable weight. Air and courier shipments only; always `null` for ocean and land.
`stackable`	boolean \| null	Whether the cargo can be stacked. `null` when not recorded.
`containers`	Container[]	Ocean (and rail) containers. Empty for air, courier and truck shipments. On FCL shipments these are the customer's own containers. On LCL, DDP and DDU shipments the container is a shared consolidation container: its number is useful for tracking the vessel leg, but the box and its other contents do not belong to the customer — do not count it as "their container".
`packages`	Package[]	Package lines. Each line is `quantity` identical packages. May be empty, notably on FCL shipments.

Container

Field	Type	Description
`number`	string \| null	Container number (ISO 6346). `null` until a container is assigned, which can be well after booking. Searchable with `search`.
`type`	string \| null	Container size and kind. Values: `TwentyFt`, `FortyFt`, `FortyFtHighCube`, `FortyFtTempControl`, `FortyFiveFtHighCube`.
`sealNumber`	string \| null	Seal number.

Package

Field	Type	Description
`type`	string \| null	Kind of package. Values: `Pallet`, `Box`.
`quantity`	integer \| null	Number of identical packages on this line.
`hazardous`	boolean \| null	Whether the packages contain hazardous goods.
`weight`	Weight \| null	Weight of one package.
`length`	Length \| null	Length of one package.
`width`	Length \| null	Width of one package.
`height`	Length \| null	Height of one package.

Weight

Field	Type	Description
`value`	number	Magnitude, in `unit`.
`unit`	string	Kilograms or pounds. Values: `KG`, `LB`.

Length

Field	Type	Description
`value`	number	Magnitude, in `unit`.
`unit`	string	Unit of `value`. Values: `Centimeter`, `Inch`, `Millimeter`, `Meter`.

Volume

Field	Type	Description
`value`	number	Magnitude, in `unit`.
`unit`	string	Cubic metres or cubic feet. Values: `CubicMeter`, `CubicFeet`.

Milestone

Field	Type	Description
`type`	string	Role of the milestone. For air shipments `OriginPort`, `TransshipmentPort` and `DestinationPort` are airports. A `Delivery` milestone's place may itself be a port (door-to-port). Values: `Pickup`, `OriginPort`, `TransshipmentPort`, `DestinationPort`, `InlandTerminal`, `BorderCrossing`, `IntermediaryWarehouse`, `Delivery`.
`place`	Place \| null	Where the milestone is. Always `null` for `IntermediaryWarehouse` and `BorderCrossing` milestones — only their type is given.
`warehouseType`	string \| null	Kind of warehouse, on `IntermediaryWarehouse` milestones. `CFS` is a container freight station. `null` on every other milestone type. Values: `CFS`, `ConsolidationWarehouse`, `DeconsolidationWarehouse`.
`cargoReadyDate`	string \| null	When the supplier has the cargo ready for collection. Set on the `Pickup` milestone only. Local calendar date at the place it refers to, `yyyy-MM-dd`. It has no time zone; do not convert it.
`arrival`	MilestoneDate \| null	Arrival at this milestone. `null` on the `Pickup` milestone and whenever no date is known.
`departure`	MilestoneDate \| null	Departure from this milestone. `null` on the `Delivery` milestone and whenever no date is known.
`completed`	boolean	Whether the shipment has reached this milestone: picked up for `Pickup`, arrived for every other type.
`transportToNext`	TransportToNext \| null	The leg leaving this milestone. `null` on the last milestone.

ETA is a milestone's arrival while actual is false: the DestinationPort milestone for the port of discharge, the Delivery milestone for final delivery.

MilestoneDate

Field	Type	Description
`date`	string	Local calendar date, `yyyy-MM-dd`.
`time`	string \| null	Local time, 24-hour `HH:mm`. `null` when only the date is known.
`actual`	boolean	`true`: it happened on this date. `false`: this is an estimate (ETA/ETD) and can change on any later read.

TransportToNext

Field	Type	Description
`mode`	string \| null	How the cargo moves on this leg. `Voyage` is a sea leg. Values: `Truck`, `Voyage`, `Flight`, `Rail`.
`vessel`	string \| null	Vessel name. `Voyage` legs only.
`voyageNumber`	string \| null	Voyage number. `Voyage` legs only.
`flightNumber`	string \| null	Flight number. `Flight` legs only; each flight leg of a transshipped air route has its own.
`carrier`	Carrier \| null	The carrier operating this leg. Can differ from the shipment's main `carrier`, for example on an air route flown by two airlines.