Pagination and filtering
Every list endpoint pages the same way, so a client that can page one can page all of them.
Cursors, not page numbers
A list response carries a cursor:
{
"shipments": [
{ "reference": "C3AT-XHM0" }
],
"cursor": {
"after": "eyJpZCI6NjUxfQ"
}
}
Pass after back to get the next page:
curl -H 'X-Cargoplot-Key: <token>' \
'https://api.cargoplot.com/v1/shipment?after=eyJpZCI6NjUxfQ'
cursor.after is absent when there is no next page. That absence is how you
know you have reached the end — not an empty array, which you will not get.
cursor.before works the same way going backwards, and is absent on the first
page.
Treat a cursor as opaque. It is a token that means "resume from here", and its contents are not a contract — decoding one and constructing your own will break.
Why cursors rather than ?page=3: an offset re-counts rows on every request, so a
new shipment arriving mid-pass shifts everything down and you silently skip a
record. A cursor resumes from a fixed point instead.
Page size
limit accepts 50 by default and
100 at most.
Asking for more than the maximum is refused with a 400, not quietly reduced.
That is deliberate: a silently truncated page looks exactly like the end of the
data, and a client that trusts it skips records without ever knowing.
Sorting
order_by chooses the field, order the direction (ORDER_ASC or ORDER_DESC,
newest first by default). The available order_by values differ per resource —
see the spec for each endpoint's list.
Shipments and inquiries can be sorted by the time they last changed:
SHIPMENT_ORDER_BY_UPDATE_TIME and INQUIRY_ORDER_BY_UPDATE_TIME sort on the
record's update_time, in both directions, and break a tie by id so that no
record is skipped or repeated across pages. Sorted oldest first, they are the
basis of keeping a copy in sync.
A cursor only continues the query that returned it. Keep order_by, order,
filter (or any filter.<field>) and search the same for the whole pass, and on
/v1/shipment/{shipment}/invoice the shipment too. A cursor sent with any of them
changed, from another list, or one that is not a cursor at all, is refused with a
400 that says so. That is your request's mistake, so
retrying it unchanged will not help: start again from no cursor
if you need a different query. limit may change from one page to the next.
Filtering and search
Filter expressions
The shipment, inquiry and invoice lists take a filter in filter: an
AIP-160 expression, the filtering syntax and
parameter name of Google's API design guide. The invoice lists are
/v1/invoice and /v1/shipment/{shipment}/invoice, and on the second one the
expression narrows within that shipment.
curl -G -H 'X-Cargoplot-Key: <token>' 'https://api.cargoplot.com/v1/shipment' \
--data-urlencode 'filter=(port_of_loading = "CNSHA" OR port_of_loading = "CNNBO") AND port_of_discharge = "NLRTM" AND status != STATUS_CANCELLED'
Each term compares a field with a value. Terms combine with AND, OR and NOT
(also written as a leading -), and parentheses group them.
OR binds tighter than AND, the other way round from most languages:
a AND b OR c means a AND (b OR c). Put parentheses around every OR and the
question is never in doubt.
The fields carry the names the response gives them:
| Field | Shipments | Inquiries | Invoices | Value |
|---|---|---|---|---|
status | yes | yes | yes | an enum value as the response spells it, unquoted: STATUS_ACTIVE, or STATUS_PAID on an invoice |
transport_mode | yes | TRANSPORT_MODE_SEA | ||
transport_modes | yes | a list, matched with :: transport_modes:TRANSPORT_MODE_SEA | ||
cargo_type | yes | yes | CARGO_TYPE_CONTAINERS | |
incoterm | yes | INCOTERM_FOB | ||
incoterms | yes | a list, matched with :: incoterms:INCOTERM_FOB | ||
origin.locality, destination.locality | yes | yes | quoted text, matched exactly but case-insensitively: "Shanghai" | |
origin.region_code, destination.region_code | yes | yes | a quoted two-letter code: "NL" | |
port_of_loading, port_of_discharge | yes | yes | a quoted UN/LOCODE: "NLRTM" | |
etd, eta | yes | a quoted day, also with <, <=, > and >=: eta >= "2026-12-10" | ||
cargo_ready_date | yes | yes | a quoted day, as etd | |
issue_date, due_date | yes | a quoted day, as etd: due_date < "2026-12-01" | ||
update_time | yes | yes | a quoted RFC 3339 time, with >= only: update_time >= "2026-11-10T06:55:00Z" | |
shipping_line, vessel | yes | quoted text, matched exactly but case-insensitively | ||
client_references | yes | yes | your own order numbers, matched with : against one whole reference, case-insensitively: client_references:"S05749" | |
credited_invoice_id | yes | the quoted id of the invoice that a credit note or a corrective invoice names, as the response shows it: credited_invoice_id = "7" |
A client reference matches whole. client_references:"S0579" finds a
shipment or inquiry holding S0579 and never one holding only S05794, and
* is an ordinary character there, not a wildcard. NOT client_references:"S0579"
leaves out the ones holding S0579, and keeps the ones with no references at all.
An invoice list takes the same expression, for example the paid invoices due before December:
curl -G -H 'X-Cargoplot-Key: <token>' 'https://api.cargoplot.com/v1/invoice' \
--data-urlencode 'filter=status = STATUS_PAID AND due_date < "2026-12-01"'
credited_invoice_id takes the id, not the reference. To list the credit notes
and corrective invoices of an invoice you know by the number printed on it, read
that invoice with GET /v1/invoice/{invoice} first and filter on the id it
returns. An invoice outside your organization matches nothing and answers an
empty page, not a 404.
Days are whole UTC days, and every bound includes its day.eta <= "2026-12-15" keeps a shipment arriving late on the 15th,
eta > "2026-12-15" starts on the 16th, and eta = "2026-12-15" is that whole
day. A bound is not nudged by the caller's own offset. Sub-day precision is not
accepted on a day field; to narrow within a day, filter on the day and compare
timestamps client-side. update_time is the exception: it is a time, not a day,
and takes >= and nothing else.
Excluding keeps records whose field is empty.transport_mode != TRANSPORT_MODE_SEA includes the shipments that have no
transport mode, and
NOT (port_of_discharge = "NLRTM" OR origin.locality = "Shanghai") keeps a
shipment without an origin city. A comparison without NOT or != never
matches an empty field, so eta >= "2026-12-10" leaves out the shipments with no ETA.
A region code matches the records that hold one, which are the records whose
response shows a region_code.
The expression is AND-ed with search and, while they last, with the deprecated
typed filters below. It is refused with a 400 naming
the problem when it uses a field the list does not have, an operator its field
does not take (: on a city, < on a status), a value its field cannot hold,
or an enum value nothing is filtered on, such as STATUS_UNSPECIFIED; and when
it runs over 1000 characters or 20 comparisons.
Spaces, quotes and < and > have to be URL-encoded;
curl -G --data-urlencode, as above, does it for you.
Deprecated: typed filters
The shipment list still accepts filter.status, filter.etd and filter.eta,
the inquiry list filter.status and filter.cargo_ready_date, and both invoice
lists filter.status, filter.issue_date, filter.due_date and
filter.credited_invoice_id. They are deprecated: they work as before, but
are no longer in the spec and will be removed. The
changelog announces the date first.
Each one is a term of the expression. A date parameter takes the same four shapes
on every list, so filter.issue_date and filter.due_date convert like
filter.etd:
| Typed filter | Expression in filter |
|---|---|
filter.status=STATUS_ACTIVE&filter.status=STATUS_ON_HOLD | status = STATUS_ACTIVE OR status = STATUS_ON_HOLD |
filter.status=STATUS_PAID&filter.status=STATUS_DISPUTED | status = STATUS_PAID OR status = STATUS_DISPUTED |
filter.etd=2026-07-01 | etd = "2026-07-01" |
filter.etd=gte:2026-07-01 | etd >= "2026-07-01" |
filter.etd=lte:2026-07-31 | etd <= "2026-07-31" |
filter.etd=2026-07-01..2026-07-31 | etd >= "2026-07-01" AND etd <= "2026-07-31" |
filter.issue_date=gte:2026-07-01 | issue_date >= "2026-07-01" |
filter.due_date=2026-07-01..2026-07-31 | due_date >= "2026-07-01" AND due_date <= "2026-07-31" |
filter.credited_invoice_id=7 | credited_invoice_id = "7" |
filter.credited_invoice_id also takes the reference of the invoice, the number
printed on it, which the expression does not: fetch the invoice with
GET /v1/invoice/{invoice} and filter on the id it returns, as
above.
Combine several with AND, with parentheses around each OR.
Unknown parameters
A query parameter the API does not know is ignored, not refused. A misspelt
fliter answers with the unfiltered list, and so does a deployment from
before a parameter existed, with one exception: a deployment from before
filter took an expression refuses it with a 400. The
changelog says when each parameter arrived.
Search
search is free text across the fields a human would search, which differ by
resource. On a shipment they include its reference, description, client
references, MBL and container numbers, vessel, ports and origin or destination
city; on an inquiry, its reference, description, client references and origin or
destination city; on an invoice, its reference. It narrows the result set; it
does not reorder it, so a better match does not float to the top.
Search matches loosely. A client reference is found whole, by its start
(S0574 finds S05749), by its end, or by the part after a separator
(2026-118 finds PO-2026-118), but a short fragment from its middle is not,
and a search for S05749 can also return a neighbour such as S05748. To match
one reference exactly, use the client_references filter above.
Filters and search combine, and combine with paging. Applying them server-side is almost always cheaper than fetching everything and filtering locally — and it spends far less of your rate limit.
Walking a whole list
cursor=''
while :; do
page=$(curl -sH "X-Cargoplot-Key: $TOKEN" \
"https://api.cargoplot.com/v1/shipment?limit=100&after=$cursor")
echo "$page" | jq -r '.shipments[].reference'
cursor=$(echo "$page" | jq -r '.cursor.after // empty')
[ -n "$cursor" ] || break
done
The loop ends because cursor.after disappears, which is the only reliable
signal. Stopping when a page comes back shorter than limit is a common habit and
it is wrong here — a filtered page can be short and still have more after it.
Keeping a copy in sync
If you keep a copy of your shipments or inquiries, you do not have to fetch all of
them each time. Every shipment and inquiry carries an update_time, the time it
last changed, and the lists can sort and filter on it, so "what changed since my
last run" is one paged walk.
What moves update_time. Any change to a field of the shipment or inquiry as
the response shows it: its status, dates, origin and destination, and the
containers or cargo components of the cargo. An ETA that a tracking event
changes counts too, because the ETA is a field of the shipment. What does not: its
quotes, documents, invoices, and chat and customs messages, and the tracking
events themselves. Those have endpoints of their own, so read them there.
Creating a quote, or a price update on a shipment, can still move the time, so a
record can come back with nothing changed.
The recipe is the same for both lists, shown here for shipments:
- First run. Walk the whole list, oldest change first, with
order_by=SHIPMENT_ORDER_BY_UPDATE_TIME&order=ORDER_ASC. Store each shipment with itsupdate_time, and keep the largestupdate_timeyou saw asT. - Every later run. Filter on
update_time >= "<T minus 5 minutes>", sorted the same way, and followcursor.afterto the end:curl -G -H 'X-Cargoplot-Key: <token>' 'https://api.cargoplot.com/v1/shipment' \ --data-urlencode 'order_by=SHIPMENT_ORDER_BY_UPDATE_TIME' \ --data-urlencode 'order=ORDER_ASC' \ --data-urlencode 'limit=100' \ --data-urlencode 'filter=update_time >= "2026-11-10T06:55:00Z"'
Store each shipment you do not hold yet, replace your copy of each one whoseupdate_timediffers from the one in the response, skip the ones that match, and moveTto the largestupdate_timeyou saw. When nothing came back,Tstays where it was. - Now and then, for example every week, walk the whole list without a filter,
store each shipment you do not hold yet, replace each one whose
update_timediffers from your copy, and drop the shipments you hold that are no longer in it.
For inquiries, use /v1/inquiry and INQUIRY_ORDER_BY_UPDATE_TIME.
Why five minutes. Cargoplot stamps update_time when it starts saving a
change, so a change that is committed a moment after your run read the list can
carry a time just before the largest one you saw. Starting five minutes earlier
catches it, and skipping what you already hold makes the overlap free. A change
that takes longer than five minutes to commit could still slip through, which the
full walk of step 3 repairs.
Why oldest first. A record that changes while you page gets a later
update_time, so it moves behind your cursor and comes back on a later page.
Sorted newest first, the same record would jump to the front, ahead of your
cursor, and that pass would never show its new state, so do not sync that way.
A record that leaves your list is not reported. An inquiry that is deleted and a shipment that moves to another organization simply stop appearing, which is why step 3 exists.
Each run is a new pass: it has its own filter, so it starts without a cursor. A cursor from the previous run is refused.