Shipments

Get one shipment

Use this when you already have a shipment id and want its current state: status, ETAs, route, carrier, tracking health, parties, produce, cargo totals, containers, labels and check counts. Archived shipments are still found. For tracking events and ETA history use get_shipment_timeline; for demurrage and detention use get_shipment_free_time.

get/shipments/{id}

Request

Base URL: https://trackberry.com/api/v1
URL: https://trackberry.com/api/v1/shipments/{id}
Auth: HTTP bearer

Path parameters

idstring required

The shipment id (shp_ prefix). An id from another organization, or with another prefix, is a 404.

Headers

Trackberry-Versionstring

The API version to build this response for, for example 2026-10-01. Optional: without it the organization's pinned version is used (and the organization is pinned to the latest version on its first request without the header). Applies to this request only. An unpublished version is a 400 with code invalid_version.

Response

The shipment.

object'shipment' required

Always shipment.

idstring required

The shipment id.

referencestring required

Trackberry's reference for the shipment, unique within the organization. Generated (like SHIP-20260915-K7QX) unless a person set one.

erp_referencestring nullable required

The organization's own reference for the shipment (for example a purchase order number), when one was recorded.

transport_referencestring nullable required

The number the cargo is tracked by, taken from the transport document. An ocean bill of lading number, an air waybill number or a container number. Ocean and road references are upper-cased with spaces and dashes removed; air waybills use the canonical 3-digit-prefix format.

transport_reference_type'container' | 'awb' | 'bill_of_lading' | 'null' nullable required

What kind of number transport_reference is (a container number, an air waybill or a bill of lading), or null when it is blank or matches none of them.

transport_type'ocean' | 'air' | 'road' | 'null' nullable required

How the cargo travels. Only ocean and air shipments are tracked with a carrier feed. Null when not yet known.

load_type'fcl' | 'lcl' | 'null' nullable required

Whether an ocean shipment fills its own container (fcl) or shares one with other cargo (lcl). An LCL shipment travels in the forwarder's consolidation container, so it has no free time of its own and its house_bl is never used for carrier tracking. Null when not set, and for air and road.

house_blstring nullable required

The forwarder's house bill of lading for an LCL shipment, as the forwarder wrote it. Carriers cannot resolve it, so it is never the transport_reference.

forwarder_referencestring nullable required

The forwarder's own job or file reference for the shipment, when one was recorded.

forwarder_etastring date nullable required

The date the forwarder says the cargo is available, which for LCL is later than eta because the container is unloaded at a container freight station first. Does not change eta or effective_eta.

cargo_type'ambient' | 'reefer' | 'frozen' | 'null' nullable required

The temperature regime of the cargo. Null when not yet known.

temperature_celsiusnumber nullable required

The temperature set point in degrees Celsius for refrigerated cargo, when known.

Where the shipment is in its life. draft is data read from documents that nobody has confirmed; validated means a person or the automatic checks confirmed the key facts; in_transit means the cargo is moving; arrived means it reached the port or airport; in_warehouse means it was received at the warehouse; error means processing failed (rarely used). Shipments waiting for approval are not exposed.

archivedboolean required

True when the shipment was archived. Archived shipments are hidden from list_shipments unless archived asks for them.

archived_atstring date-time nullable required

When the shipment was archived, or null when it is not archived.

validated_atstring date-time nullable required

When the key facts were first confirmed. Stays set after the status moves on to in_transit, arrived or in_warehouse. Null for a shipment never validated.

approved_atstring date-time nullable required

When the shipment was approved, either by a person or automatically because it arrived from a trusted sender. Null when no approval was recorded.

etdstring date-time nullable required

Estimated (later actual) time of departure, from the documents or the carrier.

etastring date-time nullable required

The estimated time of arrival at the destination as last stated by the documents or the carrier. This is the carrier's own figure and moves whenever the carrier changes it. Null when unknown.

effective_etastring date-time nullable required

The arrival time to plan around. It is eta when set, otherwise the earliest eta among the shipment's containers, otherwise null. The eta_after and eta_before filters of list_shipments compare against this.

original_etastring date-time nullable required

The first arrival estimate Trackberry recorded for the documented destination. Later estimates do not overwrite it, so eta minus original_eta is the total slip. Null when no estimate was ever recorded.

predicted_etastring date-time nullable required

A separate arrival prediction for the port of discharge from the tracking data source, built from vessel movements, port congestion and weather. Only some sources publish one, and only when the shipment is within about three days of arrival. It is independent of eta (the carrier's figure) and never overwrites it. Null when there is none.

producestring[] required

The distinct produce names in the shipment, from its packing lines, or from the draft entry when no packing list has been read yet.

organicboolean required

True when at least one visible packing line is marked organic.

notesstring nullable required

Free-text notes on the shipment.

public_tracking_urlstring uri nullable required

The shipment's public tracking page, which anyone with the link can open without logging in, for sending to a customer or partner. The English page; put /es before /track for the Spanish one. Null when the organization has public tracking pages turned off, or the shipment is archived or not yet validated. The link is unguessable and is replaced when the shipment's link is regenerated, so read it fresh rather than storing it.

created_atstring date-time required

When the shipment was created in Trackberry.

updated_atstring date-time required

When the shipment record last changed.

Changes

No recorded changes to this operation across all 1 revision of this API.