Shipment and Container Filter Reference

Use these filters on GET /shipments and GET /containers. The SDK accepts the same canonical names without the filter[...] wrapper. Read filter usage for complete request examples and SDK filtering for TypeScript examples.

​

Composition and values

Examples are synthetic or illustrative values. Replace dynamic identifiers and names with values from authorized API results; syntactic validity does not guarantee existence in your account. Different filter keys combine with AND. Within a key, scalar comma-separated values generally use OR; bracketed arrays generally use AND. Shipment number, port codes, owner IDs, terminal IDs, party IDs, and tags have the exceptions documented below. Never assume an array means OR for every field. Date comparisons use =, <, <=, >, or >=. Encode a range as repeated bracketed array keys, such as filter[pickup_lfd][]=FROM and filter[pickup_lfd][]=TO, with comparison operators in the values where the filter supports them. Presence expressions are exactly @exists and @not_exists. Text search is supported by shipment q/product and container search_by_* filters; ~ on an exact string filter is invalid.

​

Finite vocabularies

Container current_status values are new, on_ship, available, not_available, grounded, on_rail, picked_up, off_dock, delivered, dropped, loaded, empty_returned, awaiting_inland_transfer. Terms such as in_transit, discharged, and available_for_pickup are not current-status codes. Shipment voyage_status values are only arrived and on_ship. Party roles are shipper, consignee, notify_party, customs_broker, customer, freight_forwarder, pickup_dray_carrier. Party match operators are any and all. Boolean filters use literal true and false; the SDK supplies their exact wire representation.

​

Account-defined and lookup values

Port codes, terminal IDs, carrier SCACs, user/account/party IDs, tags, and product text are not finite universal enums. Use values from authorized API results. Port and terminal relationships can be loaded with include; carrier codes come from shipping lines; party IDs come from the parties associated with your account. User ownership IDs and creator account IDs are different identifiers. A random or inaccessible ID can return no matches. Supplying an ID never expands account access.

​

Shipment filters

​

Shipment aliases

Top-level number, q, and tracking_stopped are compatibility aliases; nested filters take precedence. Top-level q is deprecated, and a blank top-level q returns 400. No sunset date is documented. Shipment number is an exact shipment-number lookup, not a container-number search.

​

Shipment combinations to avoid

• actively_tracked=true with tracking_stopped=true, or both false: contradictory tracking populations.
• voyage_status=arrived with pod_ata_at=@not_exists: arrived requires actual POD arrival.
• voyage_status=on_ship with pod_ata_at=@exists: on_ship requires actual POD arrival to be absent.
• pod_eta_changed_at with stopped tracking or voyage_status=arrived: the ETA-change filter already selects active, unarrived voyages.
• arriving_today as a substitute for pod_arrival: arriving_today also checks destination milestones.

The API generally returns no matches for contradictory scopes. The SDK rejects the proven contradictions above and malformed inputs before sending a request.

​

Container filters

​

Missing data and selectors

has_holds=false means an explicitly empty terminal holds array; it does not mean “no reported hold information.” Likewise, fee selectors can exclude containers without terminal data. Do not infer total account coverage by adding true and false counts. requires_attention=false is not the exact complement of true because true also checks deadline and pickup predicates. The API treats eta_changed_in_last_24h=false and eta_changed_in_past_3_days=false as positive selectors. It treats shipment arriving_today=false as a no-op. Omit these filters to disable them; the SDK accepts only true. Relative dates and “today” use the API’s server day, while ETA-change comparisons evaluate meaningful changes to the POD-local ETA date.

​

Currently unavailable container filters

The following controller-defined inputs did not provide usable filtering in authenticated deployed checks on 2026-10-05. They are excluded from the supported SDK/OpenAPI filter catalog pending API verification or correction. These alternatives have different milestone semantics; choose the one matching the question. The SDK produces an actionable ValidationError for the unavailable inputs.

​

Sorting and pagination

Sorting and include change order/response shape; they do not scope the collection. Shipment default order is newest creation first. Container default order is most recent status refresh first. Container pages cap at 50; larger API requests are truncated. Shipment requests use the SDK’s conservative page-size cap of 100. Use page numbers starting at 1. The SDK list methods return one page. Use links.next or a bounded iterator to continue. meta.total is the filtered collection total; it is not the number of rows fetched. Mark a row-based answer partial while more pages remain, and preserve every filter across subsequent pages. Unknown API filter keys and unknown party roles are ignored rather than rejected. The SDK rejects unknown keys/roles and unsupported sort tokens to prevent account-wide results from being mistaken for a scoped answer. Never treat an HTTP 200 response alone as proof that a filter applied.