# 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](https://developers.gocubic.io/openapi.json) 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](https://developers.gocubic.io/shipment-types.md).

```jsonc
{
  "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](#place) \| null | Where the cargo is collected. |
| `portOfLoading` | [Place](#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](#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](#place) \| null | Where the cargo is delivered. May itself be a port (door-to-port), an Amazon fulfilment centre, or an address. |
| `carrier` | [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) | 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](#parcels) \| null | Last-mile parcel tracking. `null` when there is none. Present on courier shipments and on many DDP/DDU shipments. |
| `amazon` | [Amazon](#amazon) \| null | Amazon inbound identifiers. `null` when there are none. |
| `cargo` | [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](#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](#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](#weight) \| null | Total gross weight of the shipment. |
| `totalVolume` | [Volume](#volume) \| null | Total volume of the shipment. |
| `chargeableWeight` | [Weight](#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](#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)[] | 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](#weight) \| null | Weight of one package. |
| `length` | [Length](#length) \| null | Length of one package. |
| `width` | [Length](#length) \| null | Width of one package. |
| `height` | [Length](#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](#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](#milestonedate) \| null | Arrival at this milestone. `null` on the `Pickup` milestone and whenever no date is known. |
| `departure` | [MilestoneDate](#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](#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](#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. |