Cargoplot APICargoplot API
API docs
OpenAPI spec

Cargoplot API changelog

Changes to the public v1 API, newest first. Written for someone integrating against it: what moved, and what they have to do about it.

The spec at /openapi.json is served from the running API, so a change reaches consumers the moment it deploys. The spec says what the contract is now; this file is the only place that says what changed.

Changes land under an ## Unreleased heading while they are only on dev. Production shows that heading as the date the release reached it.

2026-11-17

A booking that breaks several rules can be refused for another of them first.

  • Changed: the order of a booking's refusals. POST /v1/quote/{quote}/accept checks your preferred sailings where the app's bookings are checked, so a booking that breaks more than one rule can be answered with another of them first: two preferred sailings naming one sailing, and for a generated price your organization's missing details, now come before a sailing the quote does not offer or that can no longer be booked. The refusals and their messages are unchanged.

2026-11-16

You can tell from a booking's 409 that your organization's details are incomplete.

  • Changed: a booking can be refused while your organization's details are incomplete.POST /v1/quote/{quote}/accept can answer 409 when the inquiry's organization lacks its address, postal code, city, VAT number or 2-letter country code. The message names the missing fields. Complete them in the app, then book again. Nothing about the booking itself changes.

2026-11-16

You can filter your invoices with the same expression as your shipments and inquiries, keep your own reference on each entry of your address book, see when a stored quote last changed, and use five more order field keys, and the typed filters of the invoice lists are deprecated.

  • Added: five order field keys. The fields of GET /v1/profile/organization/order-settings also hold ship_to, port_of_loading, incoterm, description and status. By default they are used and not required, and only status is in the table. A read adds them at the end of a saved list, as for any key the list does not hold.
  • Added: update_time on quotes. Every quote that GET /v1/inquiry/{inquiry}/quotes, GET /v1/quote/{quote}/details and POST /v1/quote/{quote}/accept return carries the time its stored record last changed, as an RFC 3339 timestamp. It is null on a generated price, which is worked out on every listing rather than stored. Nothing else about a quote changes. Assistants have it in the tools list_inquiry_quotes and get_quote_details.
  • Docs: nothing for a consumer, two user descriptions reworded. The descriptions of the UserResponse schema and of its organization_id read differently; the fields, their types and the JSON are unchanged.
  • Added: client_reference on an address book entry. GET /v1/address returns the reference of each entry from your own system, such as its supplier number, and an empty value when there is none. POST /v1/address and PATCH /v1/address/{address} set it, trimmed of surrounding whitespace, with at most 64 characters and no line breaks. An empty value clears it, and a PATCH without the field keeps it. Two entries can have the same reference. You cannot search or filter on it. The app shows the same value as "Your reference". Assistants have it in the tool list_addresses.
  • New: filter on the invoice lists takes an expression. GET /v1/invoice and GET /v1/shipment/{shipment}/invoice take an AIP-160 filter, the same syntax as on shipments and inquiries, AND-ed with search and, while they last, with the deprecated typed filters below. status takes an enum value spelled as the response spells it (STATUS_PAID); issue_date and due_date a quoted day, also with <, <=, > and >=, on whole UTC days; credited_invoice_id the quoted id of the invoice that a credit note or a corrective invoice names, as the response shows it. On the list of a shipment, the expression narrows within that shipment. Terms combine with AND, OR, NOT and parentheses, and OR binds tighter than AND, so put parentheses around every OR. NOT and != keep invoices whose field is empty. An unknown field, an operator a field does not take, or a value it cannot hold is refused with 400. For example: status = STATUS_PAID AND due_date < "2026-12-01". A deployment from before this release refuses filter= on these lists with 400.
  • Deprecated: the typed filters of the invoice lists. filter.status, filter.issue_date, filter.due_date and filter.credited_invoice_id on both invoice lists work exactly as before but are no longer in the spec. They will be removed; the date is announced here first. Each is a term of the expression: filter.status=STATUS_PAID&filter.status=STATUS_DISPUTED is filter=status = STATUS_PAID OR status = STATUS_DISPUTED, filter.issue_date=gte:2026-07-01 is filter=issue_date >= "2026-07-01", filter.due_date=2026-07-01..2026-07-31 is filter=due_date >= "2026-07-01" AND due_date <= "2026-07-31", and filter.credited_invoice_id=7 is filter=credited_invoice_id = "7". The typed filter also took the reference of the credited invoice, which the expression does not: fetch the invoice with GET /v1/invoice/{invoice} and filter on the id it returns.

2026-11-12

You can page your shipments and inquiries by the time they last changed to keep a copy of them in sync, and a request that needs data the API has not loaded yet answers 503 to retry instead of waiting.

  • Added: page shipments and inquiries by the time they last changed. GET /v1/shipment takes order_by=SHIPMENT_ORDER_BY_UPDATE_TIME and GET /v1/inquiry takes order_by=INQUIRY_ORDER_BY_UPDATE_TIME, in both directions, and both take filter=update_time >= "<RFC 3339 time>", with >= only. Together they keep a copy of your shipments and inquiries in sync without fetching everything each time. On the first run, walk the list sorted by update time, oldest first, store each record with its update_time, and keep the largest update_time that you saw. On every later run, filter on update_time >= "<that time minus 5 minutes>", sorted oldest first, follow cursor.after to the end, replace each record whose update_time differs from the one that you hold, and keep the new largest update_time. The five minutes cover a change that Cargoplot saves a moment after your previous run read the list. A record that changes while you page moves behind your cursor, so it comes back on a later page. Any field of a shipment or an inquiry moves its update_time, an ETA that a tracking event changes included. Its quotes, documents, invoices and messages do not, though creating a quote or a price update can, so a record can come back with nothing changed. A record that leaves your list is not reported: an inquiry that is deleted, or a shipment that moves to another organization. Now and then, for example every week, walk the whole list, replace each record whose update_time differs, and drop the ones that are gone. Assistants have it in the tools list_shipments and list_inquiries.
  • Changed: a request that needs data the API has not loaded yet answers 503. An instance takes requests only once it has loaded its data, so you should rarely see this; if you do, the answer is 503 Service Unavailable, where the request used to wait and could time out. Retry it after a few seconds.

2026-11-12

A shipment field that carried no information for integrators is removed.

  • Removed a shipment field that carried no information for integrators.

2026-11-11

You can read the terms and conditions you book under with links to their documents, tell from a booking's 403 that they still have to be accepted in the app, and see when an inquiry is too large for an automatic price, so our sales team prepares its quote.

  • Added: the terms and conditions you book under. GET /v1/profile/terms returns the current terms and conditions of the authenticated user: the terms of their platform and the FENEX conditions, or the FENEX conditions alone, each with its name, label, version and a download_url of its English PDF, and needs_acceptance, true until the user has accepted them in the app. It cannot accept them. platform_name and each document's kind say whose terms they are, so you can word the terms a booking is made under. It answers 503 while the documents cannot be read; try again later.
  • Changed: a booking needs the current terms and conditions accepted. Once Cargoplot turns the check on, POST /v1/quote/{quote}/accept answers 403 to a user of a client organization who has not accepted the current terms and conditions of their platform and the FENEX conditions, as the app does. The message starts with tac_acceptance_required: the user signs in to the app to review and accept them, and then books again. A booking that already went through is still answered with 200 and that booking, and users of other organizations are not checked. needs_acceptance of GET /v1/profile/terms tells beforehand whether the user still has to accept them.
  • Docs: large inquiries and short chat messages. POST /v1/inquiry now says that a full-container inquiry over our container limit, or a groupage inquiry over our volume limit, gets no automatic price and is quoted by our sales team, as its size_limit shows. The text of POST /v1/shipment/{shipment}/chat/message, /v1/inquiry/{inquiry}/chat/message and /v1/shipment/{shipment}/customs/message recommends under 500 characters and one question or request per message, for the fastest handling. The limit stays at 10,000 characters.
  • Added: size_limit on an inquiry over a size limit. An inquiry with more containers in total than our container limit, or a groupage inquiry with more volume than our volume limit, gets no automatic price: our sales team prepares its quote and contacts the person who submitted it. InquiryResponse (every inquiry read and write) and GET /v1/inquiry/{inquiry}/quotes then carry a size_limit object with the measure (MEASURE_CONTAINERS or MEASURE_VOLUME_CBM), the maximum and a message in English to show to the user, which names our sales team's phone number and email address. The field is absent while the inquiry is within the limits, and an inquiry is checked when it is created and whenever its cargo changes.

2026-11-11

A finished sea shipment found by its container number keeps its tracking milestones.

  • Fixed: a finished sea shipment found by container number keeps its tracking milestones.GET /v1/shipment/{shipment}/tracking returned the recorded milestones of a finished full-container shipment with a bill of lading number, but still answered with an empty events list when the shipment could only be matched by container number: a full-container shipment without a bill of lading number, or one shipped as packages or pallets. It now returns them there too. A container is reused from voyage to voyage, so such a record is used only when its departure falls within 14 days of the shipment's ETD. Without an ETD or a departure date, a record is used when it was created no earlier than 30 days before the shipment, a looser test that cannot always tell two voyages of one container apart.

2026-11-10

You can read the chat and customs messages of your shipments and inquiries, post into them, and mark them read.

  • Added: the chat and customs messages of your shipments and inquiries.GET and POST on /v1/shipment/{shipment}/chat/message, /v1/inquiry/{inquiry}/chat/message and /v1/shipment/{shipment}/customs/message read and post into one conversation each. A list is cursor-paginated and newest first, with order for the other direction and a send_time >= "<time>" filter for polling; >= is the only operator, as it is for the other timestamp filters. Start a poll from the last send_time you saw minus a few minutes and skip the ids you saw: a message is listed a moment after it is sent. Each message has its author, text, channel, conversation, whether you have read it, and the names and media types of its attachments, which cannot be downloaded here. A post is made as the authenticated user, with the same notifications as a message written in the app, answers 201 with the message, and takes an Idempotency-Key. A reply in a customs conversation is only accepted once the shipment's customs conversation holds a message: otherwise 409. POST .../chat/read and .../customs/read mark the conversation read up to and including the message named in message, for the authenticated user and their organization, as reading in the app does, and answer 204. Another organization's shipment or inquiry answers 404, and an inquiry has no customs conversation. A shipment booked from an inquiry has its reference, so both paths of its chat show one conversation. The paths /v1/shipment/{shipment}/chat, /v1/inquiry/{inquiry}/chat and /v1/shipment/{shipment}/customs are kept for a later resource.

2026-11-05

Two preferred sailings can be on the same vessel when they depart on different days, and the 400 for incoterms that meet the exclusions an inquiry already has names those exclusions.

  • Changed: the 400 when incoterms meets the exclusions an inquiry already has. An update that changes incoterms without excluded_stages applies the exclusions the inquiry echoes to the new incoterms. When they cannot hold, because you send several incoterms or because they leave a CFR or CIF inquiry nothing, the 400 on incoterms now names the exclusions, as stage groups, and says to send excluded_stages with incoterms, or an empty list to drop them. An update that sends excluded_stages itself gets the message it got before.
  • Changed: two preferred sailings on one vessel are allowed when they depart on different days. The booking, POST /v1/quote/{quote}/accept, refused two preferred_sailings that named the same carrier and vessel, whatever their departures, so a first choice and a fallback on the vessel's next rotation could not both be given. Two preferences now clash only when carrier, vessel and the day of the etd in UTC are all the same, so the same sailing with another time of day still answers 400. A sailing without an etd only clashes with another without one. Nothing else about preferred_sailings changes.

2026-11-05

You can leave the parts of the transport you arrange yourself out of an inquiry, see which parts a quote covers, see which invoice a corrective invoice corrects, and, with order management, create, read and delete your orders, read the check-ins that Cargoplot decides to send to the supplier of each order and the cargo ready dates that the suppliers answer, and read and change your order settings.

  • Added: covered_stages on a quote. The quote listing and a quote's details name the parts of the transport each price or quote covers, as the stage groups excluded_stages takes, plus STAGE_GROUP_MAIN_CARRIAGE. A part counts as covered when the quote covers any of its stages. A quote stored before you changed an inquiry's excluded_stages keeps what it covered, so compare the two to see whether it still matches. Who carries out a part is not published.
  • Added: excluded_stages on an inquiry. Name the parts of the transport you arrange yourself when you create or update an inquiry, as stage groups: STAGE_GROUP_PICKUP, STAGE_GROUP_EXPORT_CLEARANCE, STAGE_GROUP_DESTINATION_HANDLING, STAGE_GROUP_IMPORT_CLEARANCE or STAGE_GROUP_DELIVERY. Generated prices then leave those stages out, and a shipment booked from one has no partner for them. Main carriage cannot be left out. The field needs exactly one incoterm, and leaving out everything a CFR or CIF inquiry leaves to us answers 400. A group the incoterm already leaves out is accepted, changes nothing and is not echoed. An update that changes only incoterms keeps the exclusions the inquiry echoes; send excluded_stages with it to be sure. The response returns the exclusions in effect. Without the field nothing changes.
  • Added: orders, POST /v1/order, GET /v1/order/{order} and DELETE /v1/order/{order}. A purchase order of your organization, with your purchase_order_number, an optional supplier_order_number, the supplier_address_id of a supplier in your address book, and the cargo_ready_date of the purchase order. Each order number has at most 100 characters, and a value of only whitespace answers 400. The create answers 201 with the order. The order shows the purchase_order_cargo_ready_date that you sent, which does not change, its current_cargo_ready_date (the last supplier answer, or the purchase order date until the supplier answers), its next_check_in_date and the organization_id of its organization. Two orders can have the same purchase order number. An identical create from your organization within ten minutes returns the first order with Idempotent-Replayed: true, also without an Idempotency-Key, so a retry makes no second order. A deleted order is not replayed. Delete an order, for example for a cancelled purchase order. Cargoplot then stops asking the supplier about it. The delete answers 204, and the deleted order then answers 404. These endpoints, and all the order endpoints below, are available only to organizations with order management. Other organizations get 404. Assistants have the read as the tool get_order.
  • Added: GET /v1/order. A page of the orders of your organization, newest first. Deleted orders are not in the list. Sort with order_by on the purchase order number, the supplier order number, the supplier name or the current cargo ready date. search finds the orders whose purchase order number holds a text. Use filter with these fields: purchase_order_number and supplier_address_id (text, matched exactly but case-insensitively), current_cargo_ready_date (a day, also with <, <=, > and >=), update_time (an RFC 3339 time, with >= only) and organization_id (with = only). A supplier answer changes update_time, so to get the supplier answers, filter on update_time >= "<time>". Assistants have it as the read tool list_orders.
  • Added: check-ins, GET /v1/order/check-in and GET /v1/order/{order}/check-in. A page of the check-ins that Cargoplot decided to send to the suppliers of your orders, newest first: of all orders, or of one order. A check-in has no id: its order_id and number identify it. It shows its triggered_time, its reminder_triggered_time when Cargoplot decided to send a reminder, and its answer: the first cargo ready date that the supplier gave from that check-in until the next one, or null. Use filter with triggered_time (an RFC 3339 time, with >= only) and order_id (with = only, combined with OR for a set of orders). The check-ins of a deleted order are not in the list. Assistants have them as the read tools list_check_ins and list_order_check_ins.
  • Added: the cargo ready dates of an order, GET /v1/order/{order}/cargo-ready-date. A page of the cargo ready date history of one order, newest first. The oldest entry is the purchase_order_cargo_ready_date of the order, recorded at its create_time. Each later entry is a supplier answer. To get the dates that Cargoplot recorded from a given time, filter on record_time >= "<time>". Assistants have it as the read tool list_order_cargo_ready_dates.
  • Added: order settings, GET and PATCH /v1/profile/organization/order-settings. The order management settings of your organization, in three parts: check_ins (1 to 6 check-ins, each with its lead_days before the cargo ready date and an optional message to the supplier), fields (the order fields that the app shows) and no_answer (the days until a reminder to the supplier and until a warning to your organization, when the supplier does not answer a check-in). A part that your organization never saved has the Cargoplot defaults. The update replaces each part that the body carries as a whole, keeps the other parts, and answers the settings after the save. A read adds a key that the saved fields do not hold at the end, with its defaults. A read drops each key that the api does not know, and each later copy of a key. Assistants have the read as the tool get_order_settings.
  • Changed: credited_invoice_id can appear on an invoice whose total is not negative. A corrective invoice credits lines of an earlier invoice next to new charges, so its total need not be negative; it now names the invoice it corrects in credited_invoice_id, as a credit note names the invoice it credits. filter.credited_invoice_id matches it too. A negative total still marks a credit note, so to tell the two apart, look at the sign of the total, not at whether credited_invoice_id is set.

2026-11-04

You can read the allowance that writes made through an AI assistant spend in /api-info.json.

  • Added: assistant_write_rate_limit in /api-info.json. It has the shape of quote_rate_limit and publishes the allowance that writes made through an AI assistant spend, a booking included, ahead of every other allowance. Writes made with an API key are not counted against it. While it is off, an assistant's writes spend the allowance they would otherwise.

2026-11-03

You can send an Idempotency-Key with any write so a retried request takes effect once.

  • Added: the Idempotency-Key header on every write. Send a key of your choosing, 1 to 255 printable ASCII characters, bare or as a quoted string, with a POST, PATCH or DELETE. Sent again by the same user within 24 hours with the same request -- the same method, path, query and body, byte for byte -- it answers what the first one answered, with Idempotent-Replayed: true, and writes nothing. That includes booking a worked-out price, which answers 409 on a retry without a key. The same key with a different request answers 422; while the first request is still being processed, 409 with Retry-After; a malformed key, or one from a user who belongs to no organization, 400; and a key that cannot be checked, 503. A request that failed does not keep its key, so it can be sent again. Without the header nothing changes. A write made through an AI assistant must carry a key, or it answers 400.

2026-11-02

You can see every stored quote of an inquiry in its listing, and the spec's descriptions of a few schemas are trimmed.

  • Changed: every stored quote of an inquiry is listed. A stored quote was left out of GET /v1/inquiry/{inquiry}/quotes when a cheaper one looked the same in the listing, even if its charges or notes differed, so it could be neither read nor booked. Every stored quote is listed now, can be read through GET /v1/quote/{quote}/details and GET /v1/quote/{quote}/sailings, and booked. A worked-out price is still left out when another record looks the same in the listing and costs no more excluding VAT; on an equal price a stored quote is the one listed.
  • Docs: descriptions are trimmed. The spec's descriptions of PreferredSailing, ShipmentUpdate, the tracking locations and cargo, the shipment's port_of_loading and the organization's postal_address no longer explain how they were built, and this file no longer opens with notes for the people who write it. No behaviour, field, path or enum changes.

2026-10-30

You can read the full breakdown of a quote before you book it, list the sailings a quote can be booked on to pick a preferred sailing from them when you book it, see the incoterm and free storage days of each quote and the drop-off address of a container, and VAT rates are described as fractions.

  • Added: a quote's details, GET /v1/quote/{quote}/details. Takes the opaque id from GET /v1/inquiry/{inquiry}/quotes and returns what the app shows under View quote: the listing's record as quote, the reference of a stored quote, origin and destination, when it was published, the cargo it prices (containers with their drop-off terminal and address, or pallets and packages), its charges with their VAT category and rate, the agent fee, the VAT per currency, category and rate, the subtotal per currency, and its notes as plain text. Unset message fields are null. An id the listing no longer shows answers 404. It spends the quote allowance, and assistants have it as the read tool get_quote_details.
  • Added: incoterm and free_storage_days on the quotes listing. Two quotes that differ only in these terms used to be listed once, as the cheaper of the two; both are listed now.
  • Added: dropoff_address on a container. An inquiry's containers, and a quote's, carry the address of the drop-off terminal dropoff_terminal_code names, or null when it is unknown: a quote's is looked up from the code when none is stored. It is ignored on a request.
  • Docs: VAT rates are described as fractions. VatBreakdown.rate and InvoiceLineItem.vat_rate were described as percentages, with an example of 21; the values were always fractions (0.21 is 21%) and have not changed.
  • Added: a quote's sailings, GET /v1/quote/{quote}/sailings. Takes the opaque id from GET /v1/inquiry/{inquiry}/quotes and lists the sailings that price or quote can be booked on: carrier, vessel, cut-off, departure, arrival, transit days, the ports and when the schedule was last retrieved, sorted by departure and paged like the other lists. bookable says whether a sailing can still be chosen; pass its sailing unchanged in the booking's preferred_sailings. A quote not tied to a shipping line, or a route without a published schedule, answers an empty list. It spends the quote allowance, and assistants have it as the read tool list_quote_sailings. The booking's description now sends you here for preferred_sailings, where it said to book without them until sailings were published.

2026-10-30

A quote can be booked over the API, and the quotes listing leaves out worked-out prices once an inquiry is booked or cancelled and no longer fails when an exchange rate is missing.

  • Added: book a quote, POST /v1/quote/{quote}/accept. Takes the opaque id from GET /v1/inquiry/{inquiry}/quotes and books it, answering with the quote and the id of the shipment the booking created. Booking a worked-out price stores a copy of it as a quote and books that copy, so the quote in the answer carries a new id. The body may be empty; preferred_sailings takes at most two sailings of that quote that can still be booked, ranked 1 and 2. Booking the same stored quote again answers 200 with Idempotent-Replayed: true; booking the same worked-out price again answers 409 naming the quote the first booking made. A booking is final over the API.
  • Changed: the quotes listing leaves out worked-out prices once the inquiry is booked or cancelled. Only the inquiry's stored quotes are listed from then on, the booked one among them. Before, the booked copy and the price it was made from were both listed.
  • Changed: a missing exchange rate no longer fails the quotes listing. A price with an amount in a currency we have no rate for used to make the whole listing fail. It is listed now with total_inc_vat equal to total_ex_vat and total_estimated true. Quotes are compared on total_ex_vat.
  • Changed: quote_rate_limit counts every quote endpoint. It already covered the listing; booking spends the same allowance. The figure at GET /api-info.json is unchanged.
  • Docs: nothing for a consumer, PreferredSailing gained descriptions. Its name, its fields, their types and the JSON are all unchanged; the only difference in the spec is that its schema and fields are described.

2026-10-29

A form-encoded POST to a read endpoint is no longer served as the GET, and a method a route does not have answers 405 with an Allow header.

  • Changed: a form-encoded POST to a read endpoint is refused. A POST with Content-Type: application/x-www-form-urlencoded to a path that has only a GET route used to run that GET. It answers 405 now. Read endpoints are called with GET and a query string. POST with a JSON body to the endpoints that take one is unchanged.
  • Changed: X-HTTP-Method-Override is no longer honoured, for any method. On a form-encoded POST it named the method the request ran as, DELETE included. The header has no effect now.
  • Changed: a method a route does not have answers 405. It answered 501. The body is the same: code 12 and the message Method Not Allowed. The answer carries an Allow header listing the methods the path takes, for every route the API serves, documented or not. The other routing answers, such as 404 for an unknown path, are unchanged.

2026-10-28

You can list the prices and quotes of an inquiry, and /api-info.json reports the allowance that listing spends.

  • New: GET /v1/inquiry/{inquiry}/quotes. Lists the prices and quotes of one inquiry in one model: the prices worked out for it and the quotes prepared for it. Sort with order_by (QUOTE_ORDER_BY_RECOMMENDED by default, QUOTE_ORDER_BY_CHEAPEST or QUOTE_ORDER_BY_FASTEST); cheapest, and recommended where reliability and delays tie, order on the total excluding VAT. Pages work as on the other lists. Each record has an opaque id, and a generated price's id changes when its price does, so list again before booking. Prices restricted to a single commodity are not listed. A listing spends the quote allowance; over it answers 429.
  • Docs: port_of_discharge on InquiryResponse is described. Like port_of_loading, it is the UN/LOCODE of the requested port. Its value does not change.
  • New: quote_rate_limit in /api-info.json. It has the shape of write_rate_limit and describes the allowance quote reads are counted against instead of the shared one, because each can work out every price afresh. While it is not enabled, quote reads count against the shared allowance.

Every organization can read and change its address book through the API, and upload files into a shipment's documents.

  • New: GET /v1/address, POST /v1/address and PATCH /v1/address/{address}. The address book of your organization: its suppliers and its locations. The list shows the id and the email of each entry. Use ?kind= to get one kind only. Archived entries are not in the list. A supplier needs an email. The update changes only the fields that you send, so {"email": "new@example.com"} keeps the name, the phone and the postal address. The kind of an address does not change.
  • Changed: an expired or invalid confirm link answers 410. GET and POST /confirm/{token} answer 410 Gone when the token is expired or not valid. Before, a JSON request got 500. A browser still gets the error page.
  • Docs: the Supplier of a shipment or an inquiry is not an address book entry. It has no id, and the address book endpoints do not show it.

A credit note names the invoice it credits as credited_invoice_id, you can list the credit notes for one invoice, and search on the inquiry and shipment lists also finds a record by its client_references.

  • New: credited_invoice_id on InvoiceResponse. On a credit note, the id of the invoice it credits; fetch that invoice through GET /v1/invoice/{invoice}. The field is absent on an invoice and on a credit note that names no invoice; credit notes issued before this release name none. A credit note is an invoice with negative totals, which is how to tell the two apart; there is no separate kind field.
  • New: filter.credited_invoice_id on GET /v1/invoice and GET /v1/shipment/{shipment}/invoice. Lists the credit notes that credit one invoice, given by its numeric id or its reference, the way GET /v1/invoice/{invoice} takes it. An invoice outside your organization matches nothing, and answers an empty page rather than 404.
  • Changed: search on GET /v1/inquiry and GET /v1/shipment also matches client_references. A 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 (0574 does not find S05749). Like the rest of search the match is fuzzy, so neighbouring references can come up too. To match one reference exactly, filter on it: client_references:"S05749", which is unchanged. Records without references match the same terms as before.

You can upload a file into a shipment's document slot, or into the shipment without naming one, and /api-info.json reports the upload allowance and the largest file.

  • New: POST /v1/shipment/{shipment}/document/{slot}. Puts a file into one slot of a shipment's document list, the way an upload in the app does: the slot becomes STATUS_RECEIVED, provided_on is set and a rejection_reason is cleared. {slot} is the slot's id from GET /v1/shipment/{shipment}/document, not the document.id. Send JSON with the file base64 encoded: {"file_name": "invoice.pdf", "content": "<base64>"}. The answer is the slot, with its document set. A slot that holds a file, or was rejected, takes a new one. Sending the same bytes again writes nothing and answers the slot with Idempotent-Replayed: true.
  • New: POST /v1/shipment/{shipment}/document. The same upload without a slot, for a file nobody made a slot for, or when you do not want to match slots yourself. The body is the same, plus an optional type (for instance TYPE_COMMERCIAL_INVOICE) and label. Without a type the file is classified from its name and text, as a file that arrives by email is; a type you may not upload (delivery order, master bill of lading, master airway bill, arrival notice) is never chosen for you, the file goes into a new TYPE_OTHER slot, and naming one is 400. The one open slot of the type takes the file (200); with none open a slot is created (201), labelled with label, or for TYPE_OTHER with the file name. Several open slots of the type answer 409 with their ids: upload into the one you mean with the per-slot endpoint, which is also how to choose a supplier's slot, as on a shipment with several suppliers that is the usual answer for commercial invoices, packing lists and house bills of lading. A shipment holds one insurance certificate: once it has a file, another is 409 with its slot id. The same bytes already on the shipment write nothing and answer that slot with Idempotent-Replayed: true.
  • The file is recognised by its content. PDF, DOCX, XLSX, TXT (valid UTF-8), PNG, JPG and GIF are accepted, at most 15 MiB once decoded and not empty. Legacy .doc and .xls files and macro-enabled .docm and .xlsm files are refused: send them as PDF, DOCX or XLSX. The extension of file_name has to fit the file, or be absent: a file named invoice.bat is refused whatever it holds. A refused file answers 400 naming content or file_name. A slot you can see in the list but cannot upload into, a delivery order or an arrival notice, answers 403; a slot you cannot see, one of another shipment, and one that does not exist answer 404. Uploads have an allowance of their own, spent instead of the write allowance; over it answers 429.
  • New: upload_rate_limit and max_upload_bytes in /api-info.json.upload_rate_limit has the shape of write_rate_limit and describes the allowance uploads are counted against instead of the write allowance; while it is not enabled, uploads count against the write allowance, or the shared one when that is off too. max_upload_bytes is the largest file an upload accepts, before base64 (15 MiB).
  • Changed: a body declared over 36 MiB answers 413. Any /v1 request whose Content-Length is over 36 MiB is refused before its body is read, with {"message": "request body too large"}. It answered 400 while the body was read. A body sent without a length, and over the limit, still answers 400, and above 64 MiB the ingress answers with its own 413 page.

2026-10-21

Inquiries and shipments carry your own order or purchase-order numbers as client_references: send them when you create an inquiry, change them on the inquiry or the shipment, and filter on them.

  • New: client_references on inquiries and shipments. Your own order or purchase-order numbers, as a list such as ["S05749"]. Send them when you create an inquiry with POST /v1/inquiry and change them with PATCH /v1/inquiry/{inquiry}; InquiryResponse and ShipmentResponse return them, as an empty list when there are none. A shipment created from an inquiry starts with the inquiry's references, and from then on they are kept on the shipment. A list holds at most 20 references, each 1 to 64 characters once surrounding whitespace is trimmed, with no line break or other control character, and none twice; one that breaks a rule answers 400 naming client_references. They are stored as written, case included. A write replaces the whole list, and an empty list clears it. Once the inquiry's quote is accepted, changing them on the inquiry answers 409.
  • New: PATCH /v1/shipment/{shipment} also takes client_references. The cargo-ready date is no longer the only field it writes. The list you send replaces the shipment's, until the shipment is completed or cancelled; after that the request answers 409, and re-sending the list it already has is never refused. The two fields lock separately, so references can still change after the cargo has been picked up. A body carrying both is refused whole when either is refused. Only the cargo-ready date raises a follow-up task for the Cargoplot team; a change of references is recorded in the shipment's history.
  • New: filter on a client reference. filter=client_references:"S05749" on GET /v1/shipment and GET /v1/inquiry matches one whole reference, case-insensitively and with no wildcard, so S0579 never matches S05794. NOT client_references:"S05749" keeps the ones without references.

2026-10-19

A page cursor that does not fit the request is refused with 400 instead of answering 500 or the wrong page, tracking explains a missing timeline for rail, road and air shipments, finished shipments keep their milestones, and a shipment's cargo-ready date can be changed.

  • New: PATCH /v1/shipment/{shipment} changes the cargo-ready date. Send {"cargo_ready_date": "YYYY-MM-DD"} when the supplier's ready date moves; the answer is the shipment as GET /v1/shipment/{shipment} renders it. It is the only field that can be written: any other key answers 400, as does a date before today (in UTC). Once the cargo has been picked up (the shipment is completed or cancelled, tracking reports it loaded or later, or its ETD has come) the request answers 409; sending the date it already has is never refused. The change is recorded in the shipment's history, and the Cargoplot team handling the shipment gets a task to follow it up. Writes count against the write rate limit, as the inquiry writes do.
  • Fixed: a cursor that cannot be used answers 400, not 500. On GET /v1/shipment, GET /v1/inquiry, GET /v1/invoice and GET /v1/shipment/{shipment}/invoice, an after or before that is not a cursor, or does not fit the request, answered 500 with could not list .... Errors tells a client to retry a 500, so one that hit this retried the same cursor forever. It now answers 400, and the message says what to do.
  • Changed: a cursor only continues the query that returned it. A cursor reused with a different order_by, order, filter (or any filter.<field>) or search, or on GET /v1/shipment/{shipment}/invoice for a different shipment, is refused with the same 400, as is a cursor from another list. Some of those used to be accepted when the values happened to fit, and answered the wrong rows or an empty page without saying so. Keep them unchanged while paging, or start again without a cursor. limit may still change between pages. Cursors stay opaque, and nothing about the request or the response changes shape.
  • Heads-up: a cursor issued before this release is refused once. A client that is part-way through a pass when it deploys gets the 400 on its next page, and starts that pass again without a cursor.
  • The spec lists the 400 on GET /v1/shipment, GET /v1/invoice and GET /v1/shipment/{shipment}/invoice, and the order_by, after and before descriptions say what is refused.
  • Changed: rail and road shipments answer 200 on GET /v1/shipment/{shipment}/tracking, not 400. The response carries etd and eta when known, and a rail or road key whose status is RAIL_TRACKING_STATUS_UNAVAILABLE or ROAD_TRACKING_STATUS_UNAVAILABLE: no tracking source covers these modes yet, so there are no milestones. A client that read the 400 as "not tracked" reads the status instead. Express shipments, and shipments with no transport mode recorded, still answer 400.
  • Changed: an air shipment without milestones says why. On the same endpoint, air.status was AIR_TRACKING_STATUS_UNSPECIFIED for these. It is now AIR_TRACKING_STATUS_AWAITING_WAYBILL (new) while the shipment has no air waybill, AIR_TRACKING_STATUS_AWAITING_AIRLINE_DATA while a valid waybill on an active shipment has no airline data yet, and AIR_TRACKING_STATUS_UNAVAILABLE while it is not being tracked as things stand, for example a waybill not written as NNN-NNNNNNNN or NNNNNNNNNNN, a shipment that is on hold, completed or cancelled or on or past its ETA date, or one the airline has no data for. Most of these can change when the shipment does, so keep polling, and keep testing events for emptiness rather than branching on a status. A client that rejects enum values it does not know needs to learn AIR_TRACKING_STATUS_AWAITING_WAYBILL.
  • Fixed: a finished shipment keeps its tracking history. Once an air shipment had landed or been delivered, GET /v1/shipment/{shipment}/tracking answered with an empty events list, and so did a sea container past discharge. They now return the milestones recorded for them. On sea this holds for full-container shipments with a bill of lading number.
  • The spec gains the RailTracking and RoadTracking schemas with their status enums and the new AirTrackingStatus value, and the tracking endpoint's 400 now names express shipments and a missing transport mode.

2026-10-12

Container types gain the 20' high cube.

  • New: CONTAINER_TYPE_20_HIGH_CUBE in the ContainerType enum. A 20' high cube container, labelled 20' high cube container. Send it wherever a container type is accepted; responses can now carry it too. A client that rejects enum values it does not know needs to learn this one. Existing values are unchanged.

2026-10-08

The deprecated typed filters on the shipment and inquiry lists have a removal date.

  • Removal: the typed filters go after 1 November 2026. filter.status, filter.etd and filter.eta on GET /v1/shipment, and filter.status and filter.cargo_ready_date on GET /v1/inquiry, keep working until then. Once they are removed, a request that still sends one is refused with 400. Move each to its term in filter, as the 2026-10-07 entry below shows; the full table is at https://developers.cargoplot.com/pagination. The invoice lists keep their typed filters.

2026-10-07

Shipment and inquiry lists take an expression over the fields they return in filter, and their typed filters are deprecated.

  • New: filter on GET /v1/shipment takes an expression. An AIP-160 filter, the syntax and the parameter name of Google's API design guide, AND-ed with search and, while they last, with the deprecated typed filters below. It reaches fields no filter covered before: status, transport_mode, cargo_type and incoterm take an enum value spelled as the response spells it; origin.locality, destination.locality, shipping_line and vessel take quoted text, matched exactly but case-insensitively; origin.region_code and destination.region_code a quoted two-letter code; port_of_loading and port_of_discharge a quoted UN/LOCODE; etd, eta and cargo_ready_date a quoted day, also with <, <=, > and >=, on whole UTC days. Terms combine with AND, OR, NOT and parentheses, and OR binds tighter than AND, so put parentheses around every OR. NOT and != keep shipments whose field is empty. An unknown field, an operator a field does not take, or a value it cannot hold is refused with 400. For example: (port_of_loading = "CNSHA" OR port_of_loading = "CNNBO") AND status != STATUS_CANCELLED. A deployment from before this release refuses the parameter with 400.
  • New: filter on GET /v1/inquiry takes an expression. The same syntax, over the inquiry's fields: status and cargo_type take an enum value; transport_modes and incoterms are lists, matched with the has operator (transport_modes:TRANSPORT_MODE_SEA, NOT incoterms:INCOTERM_FOB); the origin and destination, port_of_loading, port_of_discharge and cargo_ready_date work as on shipments.
  • Deprecated: the typed filters of these two lists. filter.status, filter.etd and filter.eta on GET /v1/shipment, and filter.status and filter.cargo_ready_date on GET /v1/inquiry, work exactly as before but are no longer in the spec. They will be removed; the date is announced here first. Each is a term of the expression: filter.status=STATUS_ACTIVE&filter.status=STATUS_ON_HOLD is filter=status = STATUS_ACTIVE OR status = STATUS_ON_HOLD, filter.etd=gte:2026-07-01 is filter=etd >= "2026-07-01", and filter.eta=2026-07-01..2026-07-31 is filter=eta >= "2026-07-01" AND eta <= "2026-07-31". The invoice lists keep their typed filters.

2026-10-02

The spec stops naming a brand.

  • The spec names no brand. The document title, its description, the agent_fee description of invoices, the dropoff_terminal_code descriptions and the create and cancel inquiry operations all referred to an API owner by name; they now say "the API", "the app" or "the forwarder" instead, and the contact block is gone. The X-Cargoplot-Key header and the CargoplotKey security scheme are unchanged. Only descriptive text changed; the paths, fields and values are the same. Nothing to change on your side.

2026-10-01

Writes can be given a rate limit of their own.

  • Writes have an allowance of their own. /api-info.json now reports write_rate_limit. While it is enabled, writes (anything other than GET, HEAD and OPTIONS) are counted against it instead of the shared allowance, and a write over it gets 429 with API write rate limit exceeded. While it is not, writes count against the shared allowance as before.

2026-09-30

Shipment search finds a city at either end, and references lose the brand name.

  • Shipment search matches the origin and destination city. The search parameter of GET /v1/shipment has always been described as covering the origin and destination city, but a city only matched when it also appeared in another field, such as a port. It now matches either city, as inquiry search already did, so searching for a city returns the shipments to and from it. Nothing to change on your side.
  • References are described without a brand name. The shipment and inquiry path parameters, the operations that explain them and the reference fields of shipments and inquiries called a reference a "Cargoplot reference"; they now say "reference". Only the descriptions changed: the values, their format and the paths are the same. Nothing to change on your side.

2026-09-24

Inquiries can be created and maintained through the API, not only read.

  • Create an inquiry. POST /v1/inquiry raises one for your organization and answers 201 with the inquiry as GET /v1/inquiry/{inquiry} renders it. The body carries the writeable fields of the inquiry you already read, under the same names and types; what only Cargoplot sets -- id, reference, status, the timestamps, the owner and the totals -- is left out, and sending it is refused. Required: description, origin, destination, cargo_ready_date, cargo_type, a transport mode, an incoterm, and fcl or lcl to match the cargo type. Everything else defaults to what the app's inquiry form leaves untouched. Creating an inquiry gathers no prices.
  • Retries are recognised for you. An identical create from the same organization within ten minutes is answered with the inquiry the first one made, with Idempotent-Replayed: true among the response headers, and creates nothing. There is no key to send. The same body after the window creates a new inquiry, which is how you copy one; an inquiry you have since cancelled or deleted is never replayed.
  • Update an inquiry. PATCH /v1/inquiry/{inquiry} changes the fields the body carries, read from its keys, and answers 200 with the whole inquiry. A list, an address and insured_goods_value are each replaced by what you send; inside fcl and lcl each key changes on its own. An empty value clears a field, which is refused where the field is required, and no update can leave an inquiry without cargo. Switching between containers and pallets or packages needs the new cargo in the same request, and clears the options of the kind it leaves.
  • Cancel and delete. POST /v1/inquiry/{inquiry}/cancel withdraws an inquiry and answers 200 with it in STATUS_CANCELLED; reopening one stays in the app. DELETE /v1/inquiry/{inquiry} answers 204 and takes the inquiry out of your list and reads, so deleting it again answers 404.
  • What a refusal looks like. A request that breaks rules answers 400 with a google.rpc.BadRequest in details: one entry per field, with its path (lcl.components[1].weight) and the reason. Every rule the body breaks is in one answer; on an update, whether the cargo and its options fit the stored inquiry is checked once the body passes, in an answer of its own. A key the request does not have, whether a typo or a field only Cargoplot sets such as status, answers 400 naming it in message. Once a quote has been accepted, every write except a change to description alone answers 409. An inquiry in another organization answers 404, as it does for the reads.
  • Corrected: cargo component dimensions are centimetres. The reference described width, height and depth on an LCL component, on shipments and inquiries alike, as metres. They are, and have always been, centimetres, as entered in the app; only the description was wrong, and no value changes. Send centimetres when you create an inquiry.
  • Deprecated: min_review_score. Nothing sets it any more and pricing does not use it, so the number on inquiry responses carries no meaning. It stays in /v1, which does not remove a published field, and is marked deprecated in the spec; do not build on it.

2026-09-14

Every status and milestone the API returns now says what it means, and the spec points at a glossary for the codes it does not define itself.

  • Statuses and milestones carry their meaning. Each value of a shipment, inquiry and invoice status, and of the sea and air tracking vocabularies, is now described in the spec beside the value itself. STATUS_IN_COLLECTION, CONTAINER_TRACKING_STATUS_EMPTY_TO_SHIPPER and the rest read as sentences in the reference and in any client generated from /openapi.json. No value was added, removed or renamed, and no response changed.
  • The spec links a glossary. Its externalDocs points at https://developers.cargoplot.com/glossary, which explains the code systems the API returns as plain strings -- UN/LOCODE, IATA, ISO 6346 container numbers, Incoterms -- and the vocabularies that reach the spec from the shared domain model with no description of their own: cargo and container types, transport modes, document types, VAT categories.

2026-09-07

Shipment tracking reached production, for sea and air freight.

  • Shipment tracking. GET /v1/shipment/{shipment}/tracking returns a shipment's movement timeline, addressed by Cargoplot reference or numeric id, unpaginated. The timeline sits under a key naming the transport mode and a response carries exactly one of them: sea holds one entry per container, each with its own events; air holds one overall status and one list of events, because air cargo has no container to hang milestones on. etd and eta sit beside the mode key. Events run oldest to newest and say whether they are expected or actual; an empty list is a valid answer, not an error. Air events name their airport by IATA code and carry the flight they happened on, and cargo says how much of the consignment each leg carried — omitted where more than one shipment shares the waybill, since the figures would then cover more than yours. Road, rail and express return 400.

2026-08-24

Invoices and shipment documents reached production, so the API answers what a shipment cost and what paperwork it still needs, not only where it is.

  • GET /v1/invoice lists your organization's invoices, and GET /v1/shipment/{shipment}/invoice narrows that to one shipment. Both page, sort and filter exactly like the shipment and inquiry lists, so the cursor you already handle works unchanged.
  • GET /v1/invoice/{invoice} reads one, addressed by reference (F2401-C2AE-XEE1) or numeric id, and renders it identically to one element of the list.
  • GET /v1/invoice/{invoice}/download returns the invoice PDF.
  • The API serves invoices that have been issued to your organization.
  • Amounts arrive as an object carrying the currency alongside the number, so no field has to be read in combination with another to be meaningful.
  • GET /v1/shipment/{shipment}/document returns a shipment's document checklist: every slot, with the uploaded file where there is one. A slot with no document member is still outstanding — that is how the two are told apart. The list is not paginated; a checklist is small and bounded.
  • GET /v1/document/{document}/download returns an uploaded file, with the content type it was stored as. The id is the document.id from the checklist, not the slot id.
  • The checklist covers the document types this API serves.
  • Fixed: GET /v1/inquiry sorted by reference or cargo_ready_date dropped inquiries whose value for that field is empty, from the second page onwards — silently, with no error and no short page. If you paged that endpoint sorted either way, the set you collected is incomplete and worth re-fetching. Sorting by status or create_time was never affected, and no other endpoint was.
  • The money schema is now named apiV1Money in the spec, where it was v1Money. No response changed shape, and nothing needs doing if you read the JSON directly — but a generated client will see the type renamed, and the shipment and inquiry insured_goods_value fields point at the new name too.
  • Fixed: the documented media types for MEDIA_TYPE_DOCX and MEDIA_TYPE_XLSX were each other's — DOCX was documented as Excel's application/vnd.openxmlformats-officedocument.spreadsheetml.sheet and XLSX as Word's …wordprocessingml.document. The enum values themselves never changed and no response moved, so nothing breaks; but if you mapped either to a content type from these docs, you have the two the wrong way round.
  • The media type schema is named DocumentMediaType on the reference page, where it previously showed its list of values in place of a name.

2026-08-21

First public release. The documentation site at https://developers.cargoplot.com is live, and the profile tab that mints the Personal Access Tokens the API needs is available in production.

  • Read-only — every documented operation is a GET.
  • Authenticate with a Personal Access Token in the X-Cargoplot-Key header.
  • Shipments, inquiries, organizations and users, with one cursor-pagination contract shared by every list endpoint.
  • Request limits and the conventions the spec cannot express are published at /api-info.json, along with the base URL to call.
  • The API has a base URL of its own -- https://api.cargoplot.com in production, and whatever /api-info.json reports as base_url in any other environment.
  • /openapi.json now states the host and scheme it is served from, so a generated client or an agent handed only that file has somewhere to send requests. It previously carried basePath: /api and no host, which left the host to be guessed.
  • Every rate-limited response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, so you can pace yourself instead of discovering the ceiling by hitting it. RateLimit-Reset counts seconds from now, not a timestamp. A 429 still carries Retry-After as well, which answers the narrower question of when to retry this request.
  • Every description in /openapi.json documents the contract: what an endpoint returns and what you have to handle. Notes aimed at Cargoplot's own engineers are kept out of it, so the reference stays about integrating rather than about how the service is built.