Shipments

post/{connectorId}/shipmentscreateShipment

Create a shipment

Submits a booking to the carrier. On success, returns an `orderNumber` and `consignmentNumber` (if assigned immediately by the carrier). **Collection time rules (TNT AU):** `collectionDateTime` must be 07:00–17:00, `collectionCloseTime` must be 13:00–19:00, and the window between them must be ≥ 120 minutes — all evaluated as wall-clock time local to the `collection` address, not a fixed national zone (a WA collection is checked against WA local time, not AEST). Violations return 400 with a structured `errors[]` list.

Parameters

Name	In	Required	Description
connectorId	path	✓	Database ID of the carrier connector account (from `GET /connectors`)

Request body

ConsignmentBookingRequest

Responses

201Booking created successfully

BookingResponse

400Invalid request — validation failed or carrier rejected input

Error

401Missing or invalid API key

Error

403Freight access is not active for this tenant

Error

404Connector not found or not active for this tenant

Error

429Too many requests for this API key — see Retry-After header

Error

502Carrier API returned an error or is unavailable

Error

get/shipmentslistShipments

List shipments

Returns shipments for the authenticated tenant, most recent first. Use `limit` and `offset` to page through results. Poll this endpoint to detect when `consignmentNumber` becomes available for carriers that assign it asynchronously.

Parameters

Name	In	Required	Description
limit	query	—	Number of shipments to return (1–200, default 50)
offset	query	—	Number of shipments to skip for pagination (default 0)

Responses

200Shipment list

ShipmentListResponse

401Missing or invalid API key

Error

403Freight access is not active for this tenant

Error

429Too many requests for this API key — see Retry-After header

Error

get/shipments/{id}getShipment

Get shipment detail

Returns full detail for a single shipment including sender, collection, and receiver addresses, item dimensions, and booking metadata.

Parameters

Name	In	Required	Description
id	path	✓	Datashift shipment ID (from booking response or `GET /shipments`)

Responses

200Shipment detail

ShipmentDetailResponse

401Missing or invalid API key

Error

403Freight access is not active for this tenant

Error

404Connector not found or not active for this tenant

Error

429Too many requests for this API key — see Retry-After header

Error

get/tracktrackByConsignment

Track by consignment number

Returns live tracking information for a shipment identified by its carrier consignment number. **Lookup strategy:** 1. If `carrier` is given, queries that carrier's connector directly — no shipment lookup, no fan-out. Use this when you already know the carrier (e.g. from your own shipment record) for a faster, unambiguous result. 2. Otherwise, searches your booked shipments for a matching `consignmentNumber`. If found, queries that carrier directly. 3. If no match in your shipments and no `carrier` given, fans out to all active carrier connectors and returns the first non-null result. **Carrier support:** TNT AU, BEX AU, and TGE AU all support tracking. TNT AU is currently the only carrier that returns proof-of-delivery (`pod`) — see the `TrackingInfo` schema. **Polling:** Some carriers (BEX AU) process consignments asynchronously after booking. If tracking returns `supported: true` but `tracking: null`, wait 30–60 seconds and retry.

Parameters

Name	In	Required	Description
consignment	query	✓	Carrier consignment number to look up (e.g. the `consignmentNumber` from a booking response)
carrier	query	—	Optional. Scopes the lookup to a single carrier, skipping the shipment-match and fan-out steps. Recommended when you already know the carrier.

Responses

200Tracking result. Check `supported` — if false the carrier does not expose a tracking API.

TrackingResponse

400Missing `consignment` query parameter, or `carrier` is not a recognized carrier

Error

401Missing or invalid API key

Error

403Freight access is not active for this tenant

Error

404Consignment not found in your shipments and no active carrier returned tracking data, or (with `carrier` given) no active connector exists for that carrier

Error

429Too many requests for this API key — see Retry-After header

Error

get/shipments/{id}/labelgetShipmentLabel

Get shipment label

Returns the PDF shipping label for a booked shipment. **Label availability:** Most carriers (including TNT AU) generate the label at booking time. If the label is not yet available, this endpoint returns 404 with `code: LABEL_NOT_AVAILABLE` — poll with exponential backoff until it becomes available. **Response format:** `application/pdf`. Save as a file or pipe directly to a label printer.

Parameters

Name	In	Required	Description
id	path	✓	Datashift shipment ID (from booking response or `GET /shipments`)

Responses

200PDF label

401Missing or invalid API key

Error

403Freight access is not active for this tenant

Error

404Shipment not found, or label not yet available from the carrier. Check `code` — `LABEL_NOT_AVAILABLE` means retry; anything else means the shipment ID is wrong.

LabelNotAvailableError

429Too many requests for this API key — see Retry-After header

Error