--- title: "List and search shipments" method: GET path: "/shipments" tags: ["Shipments"] --- # List and search shipments `GET /shipments` ## Request - Base URL: `https://trackberry.com/api/v1` - URL: `https://trackberry.com/api/v1/shipments` - Auth: HTTP bearer Use this to find shipments, to sync the whole book, or to answer questions like "what is arriving next week" (`eta_after` and `eta_before`) or "which shipments are in transit" (`status`). Newest first, keyset paged. Shipments still waiting for approval are never listed. Archived shipments are left out unless `archived` says otherwise. Each item is the full shipment object, the same as `get_shipment`. All parameters are optional and combine with AND. ## Query parameters - `q` string - `status` string[] - `labels` string[] - `archived` 'false' | 'true' | 'any' - `created_after` union - string, date-time - string, date - `created_before` union - string, date-time - string, date - `eta_after` union - string, date-time - string, date - `eta_before` union - string, date-time - string, date - `limit` integer - `starting_after` string ## Headers - `Trackberry-Version` string ## Response `200` A page of shipments, newest first. - object: The envelope every list endpoint returns. - `object` 'list', required: Always `list`. - `data` object[], required: The items of this page, in the order the endpoint documents. Each item is an object of the kind the endpoint returns. - `object` 'shipment', required: Always `shipment`. - `id` string, required: The shipment id. - `reference` string, required: Trackberry's reference for the shipment, unique within the organization. Generated (like SHIP-20260915-K7QX) unless a person set one. - `erp_reference` string, nullable, required: The organization's own reference for the shipment (for example a purchase order number), when one was recorded. - `transport_reference` string, 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_bl` string, 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_reference` string, nullable, required: The forwarder's own job or file reference for the shipment, when one was recorded. - `forwarder_eta` string, 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_celsius` number, nullable, required: The temperature set point in degrees Celsius for refrigerated cargo, when known. - `status` 'draft' | 'validated' | 'in_transit' | 'arrived' | 'error' | 'in_warehouse', required: 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. - `archived` boolean, required: True when the shipment was archived. Archived shipments are hidden from `list_shipments` unless `archived` asks for them. - `archived_at` string, date-time, nullable, required: When the shipment was archived, or null when it is not archived. - `validated_at` string, 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_at` string, 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. - `origin` Place, required: An origin or a destination. - `location` string, nullable, required: The city or port, normalized (for example `Rotterdam`), without the country. - `country` string, nullable, required: The country's English name (for example `Netherlands`). - `timezone` string, nullable, required: The UTC offset of the place as `+HH:MM` or `-HH:MM` (for example `+02:00`), learned from carrier data. Not an IANA time zone name. - `destination` Place, required: An origin or a destination. - `location` string, nullable, required: The city or port, normalized (for example `Rotterdam`), without the country. - `country` string, nullable, required: The country's English name (for example `Netherlands`). - `timezone` string, nullable, required: The UTC offset of the place as `+HH:MM` or `-HH:MM` (for example `+02:00`), learned from carrier data. Not an IANA time zone name. - `etd` string, date-time, nullable, required: Estimated (later actual) time of departure, from the documents or the carrier. - `eta` string, 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_eta` string, 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_eta` string, 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_eta` string, 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. - `carrier` object, required: The shipping line or airline. - `name` string, nullable, required: The carrier's name in its canonical spelling, from tracking data. Null before tracking has identified one. - `scac` string, nullable, required: The carrier's SCAC code (Standard Carrier Alpha Code), when known. - `tracking` object, required: Health of carrier tracking for this shipment. - `state` 'available' | 'unavailable' | 'pending' | 'not_started' | 'awaiting_reference' | 'none', required: What Trackberry knows about tracking. `available` means tracking data exists; `unavailable` means Trackberry asked and cannot get data (see `unavailable_reason`); `pending` means tracking was requested and nothing has come back yet; `not_started` means there is a reference but tracking has not been requested; `awaiting_reference` means it could be tracked once a bill of lading, container or air waybill number is known; `none` means tracking does not apply (for example road freight). - `status` string, nullable, required: The carrier's latest reported status in the tracking data source's own words (for example `in_transit`, `arrived`, `not_found`). Not a closed list. Null when there is none. - `unavailable_reason` 'unsupported_carrier' | 'invalid_reference' | 'not_found' | 'provider_error' | 'past_voyage' | 'null', nullable, required: Why tracking could not produce data, when it could not. `unsupported_carrier` means the carrier or reference type is not tracked; `invalid_reference` means the number is not usable; `not_found` means the carrier has no record of it yet; `provider_error` means the lookup returned nothing usable; `past_voyage` means the voyage ended long before the documents arrived so tracking was not started. Null otherwise. - `halted_reason` 'errored' | 'dropped' | 'null', nullable, required: Set when the tracking source reported that it stopped producing data. `errored` means its carrier feed failed on this reference; `dropped` means it removed the shipment from tracking. Cleared automatically when data flows again. Null otherwise. - `last_tracked_at` string, date-time, nullable, required: When Trackberry last refreshed tracking data for this shipment. Null if never. - `carrier_updated_at` string, date-time, nullable, required: When the carrier last published new data for this shipment, as opposed to when Trackberry last asked. Null when the source does not say. - `parties` object, required: The companies named on the transport document. - `consignor` string, nullable, required: The sender of the goods (shipper or supplier). - `consignee` string, nullable, required: The receiver of the goods named on the transport document. - `notify_party` string, nullable, required: The party the carrier notifies on arrival, when different from the consignee. - `produce` string[], 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. - `organic` boolean, required: True when at least one visible packing line is marked organic. - `cargo` object, required: Totals over all pallets of the shipment. Zero when no packing list has been read. - `pallets` integer, required: Number of pallets recorded for the shipment. - `boxes` integer, required: Total number of boxes over the visible packing lines. - `net_weight_kg` number, required: Total net weight of the produce in kilograms. - `gross_weight_kg` number, required: Total gross weight, produce plus packaging, in kilograms. - `containers` Container[], required: The containers of the shipment, oldest first. - `object` 'container', required: Always `container`. - `id` string, required: The container id. - `number` string, nullable, required: The ISO 6346 container number (4 letters and 7 digits, like `MSCU1234567`). - `seal_number` string, nullable, required: The seal number on the container door. - `vessel` string, nullable, required: The vessel name the documents give for this container. - `voyage` string, nullable, required: The voyage number the documents give for this container. - `port_of_loading` string, nullable, required: Where the container is loaded, as written in the documents. - `port_of_discharge` string, nullable, required: Where the container is discharged, as written in the documents. - `etd` string, date-time, nullable, required: Estimated time of departure of this container. - `eta` string, date-time, nullable, required: Estimated time of arrival of this container. When the shipment has no `eta` of its own, the earliest container `eta` becomes its `effective_eta`. - `cargo_type` 'ambient' | 'reefer' | 'frozen' | 'null', nullable, required: The temperature regime of this container. - `temperature_celsius` number, nullable, required: The container's temperature set point in degrees Celsius. - `labels` Label[], required: The labels the organization attached to the shipment, sorted by name. - `object` 'label', required: Always `label`. - `id` string, required: The label id. Use it in the `labels` filter of `list_shipments`. - `name` string, required: The label's name, unique within the organization. - `color` 'gray' | 'red' | 'orange' | 'amber' | 'green' | 'teal' | 'blue' | 'indigo' | 'purple' | 'pink' | 'null', nullable, required: The name of the palette color. - `color_hex` string, required: The color as a hex code such as `#ef4444`. - `checks` object, required: How many document checks the shipment has in each state. Use `list_checks` for the checks themselves. - `total` integer, required: All checks of the shipment. - `passed` integer, required: Checks that passed. - `failed` integer, required: Checks that failed, meaning something is wrong. - `warnings` integer, required: Checks that passed with a warning. - `skipped` integer, required: Checks skipped because their preconditions were not met. - `pending` integer, required: Checks that have not run yet. - `acknowledged` integer, required: Failed or warning checks an admin acknowledged (looked at and accepted). They are counted here instead of under `failed` or `warnings`. - `notes` string, nullable, required: Free-text notes on the shipment. - `public_tracking_url` string, 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_at` string, date-time, required: When the shipment was created in Trackberry. - `updated_at` string, date-time, required: When the shipment record last changed. - `has_more` boolean, required: True when more items exist after this page. Pass the last item's `id` as `starting_after` to fetch them. Always false for unpaged lists. ## Other responses - `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400. - `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header. - `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one. - `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced. --- [API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)