Cargoplot APICargoplot API
API docs
OpenAPI spec

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:

json
{
  "shipments": [
    { "reference": "C3AT-XHM0" }
  ],
  "cursor": {
    "after": "eyJpZCI6NjUxfQ"
  }
}

Pass after back to get the next page:

bash
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.

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.

bash
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:

FieldShipmentsInquiriesInvoicesValue
statusyesyesyesan enum value as the response spells it, unquoted: STATUS_ACTIVE, or STATUS_PAID on an invoice
transport_modeyesTRANSPORT_MODE_SEA
transport_modesyesa list, matched with :: transport_modes:TRANSPORT_MODE_SEA
cargo_typeyesyesCARGO_TYPE_CONTAINERS
incotermyesINCOTERM_FOB
incotermsyesa list, matched with :: incoterms:INCOTERM_FOB
origin.locality, destination.localityyesyesquoted text, matched exactly but case-insensitively: "Shanghai"
origin.region_code, destination.region_codeyesyesa quoted two-letter code: "NL"
port_of_loading, port_of_dischargeyesyesa quoted UN/LOCODE: "NLRTM"
etd, etayesa quoted day, also with <, <=, > and >=: eta >= "2026-12-10"
cargo_ready_dateyesyesa quoted day, as etd
issue_date, due_dateyesa quoted day, as etd: due_date < "2026-12-01"
update_timeyesyesa quoted RFC 3339 time, with >= only: update_time >= "2026-11-10T06:55:00Z"
shipping_line, vesselyesquoted text, matched exactly but case-insensitively
client_referencesyesyesyour own order numbers, matched with : against one whole reference, case-insensitively: client_references:"S05749"
credited_invoice_idyesthe 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:

bash
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 filterExpression in filter
filter.status=STATUS_ACTIVE&filter.status=STATUS_ON_HOLDstatus = STATUS_ACTIVE OR status = STATUS_ON_HOLD
filter.status=STATUS_PAID&filter.status=STATUS_DISPUTEDstatus = STATUS_PAID OR status = STATUS_DISPUTED
filter.etd=2026-07-01etd = "2026-07-01"
filter.etd=gte:2026-07-01etd >= "2026-07-01"
filter.etd=lte:2026-07-31etd <= "2026-07-31"
filter.etd=2026-07-01..2026-07-31etd >= "2026-07-01" AND etd <= "2026-07-31"
filter.issue_date=gte:2026-07-01issue_date >= "2026-07-01"
filter.due_date=2026-07-01..2026-07-31due_date >= "2026-07-01" AND due_date <= "2026-07-31"
filter.credited_invoice_id=7credited_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 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

bash
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:

  1. First run. Walk the whole list, oldest change first, with order_by=SHIPMENT_ORDER_BY_UPDATE_TIME&order=ORDER_ASC. Store each shipment with its update_time, and keep the largest update_time you saw as T.
  2. Every later run. Filter on update_time >= "<T minus 5 minutes>", sorted the same way, and follow cursor.after to the end:
    bash
    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 whose update_time differs from the one in the response, skip the ones that match, and move T to the largest update_time you saw. When nothing came back, T stays where it was.
  3. 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_time differs 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.