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}/acceptchecks 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}/acceptcan answer409when 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
fieldsofGET /v1/profile/organization/order-settingsalso holdship_to,port_of_loading,incoterm,descriptionandstatus. By default they are used and not required, and onlystatusis 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_timeon quotes. Every quote thatGET /v1/inquiry/{inquiry}/quotes,GET /v1/quote/{quote}/detailsandPOST /v1/quote/{quote}/acceptreturn 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 toolslist_inquiry_quotesandget_quote_details. - Docs: nothing for a consumer, two user descriptions reworded. The descriptions of the
UserResponseschema and of itsorganization_idread differently; the fields, their types and the JSON are unchanged. - Added:
client_referenceon an address book entry.GET /v1/addressreturns the reference of each entry from your own system, such as its supplier number, and an empty value when there is none.POST /v1/addressandPATCH /v1/address/{address}set it, trimmed of surrounding whitespace, with at most 64 characters and no line breaks. An empty value clears it, and aPATCHwithout 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 toollist_addresses. - New:
filteron the invoice lists takes an expression.GET /v1/invoiceandGET /v1/shipment/{shipment}/invoicetake an AIP-160 filter, the same syntax as on shipments and inquiries, AND-ed withsearchand, while they last, with the deprecated typed filters below.statustakes an enum value spelled as the response spells it (STATUS_PAID);issue_dateanddue_datea quoted day, also with<,<=,>and>=, on whole UTC days;credited_invoice_idthe 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 withAND,OR,NOTand parentheses, andORbinds tighter thanAND, so put parentheses around everyOR.NOTand!=keep invoices whose field is empty. An unknown field, an operator a field does not take, or a value it cannot hold is refused with400. For example:status = STATUS_PAID AND due_date < "2026-12-01". A deployment from before this release refusesfilter=on these lists with400. - Deprecated: the typed filters of the invoice lists.
filter.status,filter.issue_date,filter.due_dateandfilter.credited_invoice_idon 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_DISPUTEDisfilter=status = STATUS_PAID OR status = STATUS_DISPUTED,filter.issue_date=gte:2026-07-01isfilter=issue_date >= "2026-07-01",filter.due_date=2026-07-01..2026-07-31isfilter=due_date >= "2026-07-01" AND due_date <= "2026-07-31", andfilter.credited_invoice_id=7isfilter=credited_invoice_id = "7". The typed filter also took the reference of the credited invoice, which the expression does not: fetch the invoice withGET /v1/invoice/{invoice}and filter on theidit 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/shipmenttakesorder_by=SHIPMENT_ORDER_BY_UPDATE_TIMEandGET /v1/inquirytakesorder_by=INQUIRY_ORDER_BY_UPDATE_TIME, in both directions, and both takefilter=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 itsupdate_time, and keep the largestupdate_timethat you saw. On every later run, filter onupdate_time >= "<that time minus 5 minutes>", sorted oldest first, followcursor.afterto the end, replace each record whoseupdate_timediffers from the one that you hold, and keep the new largestupdate_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 itsupdate_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 whoseupdate_timediffers, and drop the ones that are gone. Assistants have it in the toolslist_shipmentsandlist_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 is503 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/termsreturns 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 itsname,label,versionand adownload_urlof its English PDF, andneeds_acceptance, true until the user has accepted them in the app. It cannot accept them.platform_nameand each document'skindsay whose terms they are, so you can word the terms a booking is made under. It answers503while 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}/acceptanswers403to 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 withtac_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 with200and that booking, and users of other organizations are not checked.needs_acceptanceofGET /v1/profile/termstells beforehand whether the user still has to accept them. - Docs: large inquiries and short chat messages.
POST /v1/inquirynow 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 itssize_limitshows. ThetextofPOST /v1/shipment/{shipment}/chat/message,/v1/inquiry/{inquiry}/chat/messageand/v1/shipment/{shipment}/customs/messagerecommends under 500 characters and one question or request per message, for the fastest handling. The limit stays at 10,000 characters. - Added:
size_limiton 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) andGET /v1/inquiry/{inquiry}/quotesthen carry asize_limitobject with themeasure(MEASURE_CONTAINERSorMEASURE_VOLUME_CBM), themaximumand amessagein 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}/trackingreturned the recorded milestones of a finished full-container shipment with a bill of lading number, but still answered with an emptyeventslist 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.
GETandPOSTon/v1/shipment/{shipment}/chat/message,/v1/inquiry/{inquiry}/chat/messageand/v1/shipment/{shipment}/customs/messageread and post into one conversation each. A list is cursor-paginated and newest first, withorderfor the other direction and asend_time >= "<time>"filter for polling;>=is the only operator, as it is for the other timestamp filters. Start a poll from the lastsend_timeyou 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, answers201with the message, and takes anIdempotency-Key. A reply in a customs conversation is only accepted once the shipment's customs conversation holds a message: otherwise409.POST .../chat/readand.../customs/readmark the conversation read up to and including the message named inmessage, for the authenticated user and their organization, as reading in the app does, and answer204. Another organization's shipment or inquiry answers404, 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}/chatand/v1/shipment/{shipment}/customsare 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
400whenincotermsmeets the exclusions an inquiry already has. An update that changesincotermswithoutexcluded_stagesapplies 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, the400onincotermsnow names the exclusions, as stage groups, and says to sendexcluded_stageswithincoterms, or an empty list to drop them. An update that sendsexcluded_stagesitself 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 twopreferred_sailingsthat 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 theetdin UTC are all the same, so the same sailing with another time of day still answers400. A sailing without anetdonly clashes with another without one. Nothing else aboutpreferred_sailingschanges.
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_stageson a quote. The quote listing and a quote's details name the parts of the transport each price or quote covers, as the stage groupsexcluded_stagestakes, plusSTAGE_GROUP_MAIN_CARRIAGE. A part counts as covered when the quote covers any of its stages. A quote stored before you changed an inquiry'sexcluded_stageskeeps what it covered, so compare the two to see whether it still matches. Who carries out a part is not published. - Added:
excluded_stageson 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_CLEARANCEorSTAGE_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 answers400. A group the incoterm already leaves out is accepted, changes nothing and is not echoed. An update that changes onlyincotermskeeps the exclusions the inquiry echoes; sendexcluded_stageswith 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}andDELETE /v1/order/{order}. A purchase order of your organization, with yourpurchase_order_number, an optionalsupplier_order_number, thesupplier_address_idof a supplier in your address book, and thecargo_ready_dateof the purchase order. Each order number has at most 100 characters, and a value of only whitespace answers400. The create answers201with the order. The order shows thepurchase_order_cargo_ready_datethat you sent, which does not change, itscurrent_cargo_ready_date(the last supplier answer, or the purchase order date until the supplier answers), itsnext_check_in_dateand theorganization_idof its organization. Two orders can have the same purchase order number. An identical create from your organization within ten minutes returns the first order withIdempotent-Replayed: true, also without anIdempotency-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 answers204, and the deleted order then answers404. These endpoints, and all the order endpoints below, are available only to organizations with order management. Other organizations get404. Assistants have the read as the toolget_order. - Added:
GET /v1/order. A page of the orders of your organization, newest first. Deleted orders are not in the list. Sort withorder_byon the purchase order number, the supplier order number, the supplier name or the current cargo ready date.searchfinds the orders whose purchase order number holds a text. Usefilterwith these fields:purchase_order_numberandsupplier_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) andorganization_id(with=only). A supplier answer changesupdate_time, so to get the supplier answers, filter onupdate_time >= "<time>". Assistants have it as the read toollist_orders. - Added: check-ins,
GET /v1/order/check-inandGET /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: itsorder_idandnumberidentify it. It shows itstriggered_time, itsreminder_triggered_timewhen Cargoplot decided to send a reminder, and itsanswer: the first cargo ready date that the supplier gave from that check-in until the next one, ornull. Usefilterwithtriggered_time(an RFC 3339 time, with>=only) andorder_id(with=only, combined withORfor a set of orders). The check-ins of a deleted order are not in the list. Assistants have them as the read toolslist_check_insandlist_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 thepurchase_order_cargo_ready_dateof the order, recorded at itscreate_time. Each later entry is a supplier answer. To get the dates that Cargoplot recorded from a given time, filter onrecord_time >= "<time>". Assistants have it as the read toollist_order_cargo_ready_dates. - Added: order settings,
GETandPATCH /v1/profile/organization/order-settings. The order management settings of your organization, in three parts:check_ins(1 to 6 check-ins, each with itslead_daysbefore the cargo ready date and an optional message to the supplier),fields(the order fields that the app shows) andno_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 savedfieldsdo 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 toolget_order_settings. - Changed:
credited_invoice_idcan 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 incredited_invoice_id, as a credit note names the invoice it credits.filter.credited_invoice_idmatches 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 whethercredited_invoice_idis 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_limitin/api-info.json. It has the shape ofquote_rate_limitand 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-Keyheader on every write. Send a key of your choosing, 1 to 255 printable ASCII characters, bare or as a quoted string, with aPOST,PATCHorDELETE. 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, withIdempotent-Replayed: true, and writes nothing. That includes booking a worked-out price, which answers409on a retry without a key. The same key with a different request answers422; while the first request is still being processed,409withRetry-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 answers400.
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}/quoteswhen 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 throughGET /v1/quote/{quote}/detailsandGET /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'sport_of_loadingand the organization'spostal_addressno 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 fromGET /v1/inquiry/{inquiry}/quotesand returns what the app shows under View quote: the listing's record asquote, 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 arenull. An id the listing no longer shows answers404. It spends the quote allowance, and assistants have it as the read toolget_quote_details. - Added:
incotermandfree_storage_dayson 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_addresson a container. An inquiry's containers, and a quote's, carry the address of the drop-off terminaldropoff_terminal_codenames, ornullwhen 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.rateandInvoiceLineItem.vat_ratewere described as percentages, with an example of21; the values were always fractions (0.21is 21%) and have not changed. - Added: a quote's sailings,
GET /v1/quote/{quote}/sailings. Takes the opaque id fromGET /v1/inquiry/{inquiry}/quotesand 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.bookablesays whether a sailing can still be chosen; pass itssailingunchanged in the booking'spreferred_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 toollist_quote_sailings. The booking's description now sends you here forpreferred_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 fromGET /v1/inquiry/{inquiry}/quotesand 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_sailingstakes at most two sailings of that quote that can still be booked, ranked 1 and 2. Booking the same stored quote again answers200withIdempotent-Replayed: true; booking the same worked-out price again answers409naming 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_vatequal tototal_ex_vatandtotal_estimatedtrue. Quotes are compared ontotal_ex_vat. - Changed:
quote_rate_limitcounts every quote endpoint. It already covered the listing; booking spends the same allowance. The figure atGET /api-info.jsonis unchanged. - Docs: nothing for a consumer,
PreferredSailinggained 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
POSTto a read endpoint is refused. APOSTwithContent-Type: application/x-www-form-urlencodedto a path that has only aGETroute used to run thatGET. It answers405now. Read endpoints are called withGETand a query string.POSTwith a JSON body to the endpoints that take one is unchanged. - Changed:
X-HTTP-Method-Overrideis no longer honoured, for any method. On a form-encodedPOSTit named the method the request ran as,DELETEincluded. The header has no effect now. - Changed: a method a route does not have answers
405. It answered501. The body is the same:code12 and the messageMethod Not Allowed. The answer carries anAllowheader listing the methods the path takes, for every route the API serves, documented or not. The other routing answers, such as404for 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 withorder_by(QUOTE_ORDER_BY_RECOMMENDEDby default,QUOTE_ORDER_BY_CHEAPESTorQUOTE_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 opaqueid, and a generated price'sidchanges 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 answers429. - Docs:
port_of_dischargeonInquiryResponseis described. Likeport_of_loading, it is the UN/LOCODE of the requested port. Its value does not change. - New:
quote_rate_limitin/api-info.json. It has the shape ofwrite_rate_limitand 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/addressandPATCH /v1/address/{address}. The address book of your organization: its suppliers and its locations. The list shows theidand theemailof each entry. Use?kind=to get one kind only. Archived entries are not in the list. A supplier needs anemail. The update changes only the fields that you send, so{"email": "new@example.com"}keeps the name, the phone and the postal address. Thekindof an address does not change. - Changed: an expired or invalid confirm link answers
410.GETandPOST /confirm/{token}answer410 Gonewhen the token is expired or not valid. Before, a JSON request got500. A browser still gets the error page. - Docs: the
Supplierof 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_idonInvoiceResponse. On a credit note, the id of the invoice it credits; fetch that invoice throughGET /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_idonGET /v1/invoiceandGET /v1/shipment/{shipment}/invoice. Lists the credit notes that credit one invoice, given by its numeric id or its reference, the wayGET /v1/invoice/{invoice}takes it. An invoice outside your organization matches nothing, and answers an empty page rather than404. - Changed:
searchonGET /v1/inquiryandGET /v1/shipmentalso matchesclient_references. A reference is found whole, by its start (S0574findsS05749), by its end, or by the part after a separator (2026-118findsPO-2026-118), but a short fragment from its middle is not (0574does not findS05749). Like the rest ofsearchthe 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 becomesSTATUS_RECEIVED,provided_onis set and arejection_reasonis cleared.{slot}is the slot'sidfromGET /v1/shipment/{shipment}/document, not thedocument.id. Send JSON with the file base64 encoded:{"file_name": "invoice.pdf", "content": "<base64>"}. The answer is the slot, with itsdocumentset. A slot that holds a file, or was rejected, takes a new one. Sending the same bytes again writes nothing and answers the slot withIdempotent-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 optionaltype(for instanceTYPE_COMMERCIAL_INVOICE) andlabel. Without atypethe 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 newTYPE_OTHERslot, and naming one is400. The one open slot of the type takes the file (200); with none open a slot is created (201), labelled withlabel, or forTYPE_OTHERwith the file name. Several open slots of the type answer409with 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 is409with its slot id. The same bytes already on the shipment write nothing and answer that slot withIdempotent-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
.docand.xlsfiles and macro-enabled.docmand.xlsmfiles are refused: send them as PDF, DOCX or XLSX. The extension offile_namehas to fit the file, or be absent: a file namedinvoice.batis refused whatever it holds. A refused file answers400namingcontentorfile_name. A slot you can see in the list but cannot upload into, a delivery order or an arrival notice, answers403; a slot you cannot see, one of another shipment, and one that does not exist answer404. Uploads have an allowance of their own, spent instead of the write allowance; over it answers429. - New:
upload_rate_limitandmax_upload_bytesin/api-info.json.upload_rate_limithas the shape ofwrite_rate_limitand 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_bytesis the largest file an upload accepts, before base64 (15 MiB). - Changed: a body declared over 36 MiB answers
413. Any/v1request whoseContent-Lengthis over 36 MiB is refused before its body is read, with{"message": "request body too large"}. It answered400while the body was read. A body sent without a length, and over the limit, still answers400, and above 64 MiB the ingress answers with its own413page.
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_referenceson inquiries and shipments. Your own order or purchase-order numbers, as a list such as["S05749"]. Send them when you create an inquiry withPOST /v1/inquiryand change them withPATCH /v1/inquiry/{inquiry};InquiryResponseandShipmentResponsereturn 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 answers400namingclient_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 answers409. - New:
PATCH /v1/shipment/{shipment}also takesclient_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 answers409, 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"onGET /v1/shipmentandGET /v1/inquirymatches one whole reference, case-insensitively and with no wildcard, soS0579never matchesS05794.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 asGET /v1/shipment/{shipment}renders it. It is the only field that can be written: any other key answers400, 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 answers409; 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, not500. OnGET /v1/shipment,GET /v1/inquiry,GET /v1/invoiceandGET /v1/shipment/{shipment}/invoice, anafterorbeforethat is not a cursor, or does not fit the request, answered500withcould not list .... Errors tells a client to retry a500, so one that hit this retried the same cursor forever. It now answers400, 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 anyfilter.<field>) orsearch, or onGET /v1/shipment/{shipment}/invoicefor a different shipment, is refused with the same400, 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.limitmay 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
400on its next page, and starts that pass again without a cursor. - The spec lists the
400onGET /v1/shipment,GET /v1/invoiceandGET /v1/shipment/{shipment}/invoice, and theorder_by,afterandbeforedescriptions say what is refused. - Changed: rail and road shipments answer
200onGET /v1/shipment/{shipment}/tracking, not400. The response carriesetdandetawhen known, and arailorroadkey whosestatusisRAIL_TRACKING_STATUS_UNAVAILABLEorROAD_TRACKING_STATUS_UNAVAILABLE: no tracking source covers these modes yet, so there are no milestones. A client that read the400as "not tracked" reads the status instead. Express shipments, and shipments with no transport mode recorded, still answer400. - Changed: an air shipment without milestones says why. On the same
endpoint,
air.statuswasAIR_TRACKING_STATUS_UNSPECIFIEDfor these. It is nowAIR_TRACKING_STATUS_AWAITING_WAYBILL(new) while the shipment has no air waybill,AIR_TRACKING_STATUS_AWAITING_AIRLINE_DATAwhile a valid waybill on an active shipment has no airline data yet, andAIR_TRACKING_STATUS_UNAVAILABLEwhile it is not being tracked as things stand, for example a waybill not written asNNN-NNNNNNNNorNNNNNNNNNNN, 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 testingeventsfor emptiness rather than branching on a status. A client that rejects enum values it does not know needs to learnAIR_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}/trackinganswered with an emptyeventslist, 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
RailTrackingandRoadTrackingschemas with their status enums and the newAirTrackingStatusvalue, and the tracking endpoint's400now names express shipments and a missing transport mode.
2026-10-12
Container types gain the 20' high cube.
- New:
CONTAINER_TYPE_20_HIGH_CUBEin theContainerTypeenum. A 20' high cube container, labelled20' 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.etdandfilter.etaonGET /v1/shipment, andfilter.statusandfilter.cargo_ready_dateonGET /v1/inquiry, keep working until then. Once they are removed, a request that still sends one is refused with400. Move each to its term infilter, 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:
filteronGET /v1/shipmenttakes an expression. An AIP-160 filter, the syntax and the parameter name of Google's API design guide, AND-ed withsearchand, while they last, with the deprecated typed filters below. It reaches fields no filter covered before:status,transport_mode,cargo_typeandincotermtake an enum value spelled as the response spells it;origin.locality,destination.locality,shipping_lineandvesseltake quoted text, matched exactly but case-insensitively;origin.region_codeanddestination.region_codea quoted two-letter code;port_of_loadingandport_of_dischargea quoted UN/LOCODE;etd,etaandcargo_ready_datea quoted day, also with<,<=,>and>=, on whole UTC days. Terms combine withAND,OR,NOTand parentheses, andORbinds tighter thanAND, so put parentheses around everyOR.NOTand!=keep shipments whose field is empty. An unknown field, an operator a field does not take, or a value it cannot hold is refused with400. For example:(port_of_loading = "CNSHA" OR port_of_loading = "CNNBO") AND status != STATUS_CANCELLED. A deployment from before this release refuses the parameter with400. - New:
filteronGET /v1/inquirytakes an expression. The same syntax, over the inquiry's fields:statusandcargo_typetake an enum value;transport_modesandincotermsare lists, matched with the has operator (transport_modes:TRANSPORT_MODE_SEA,NOT incoterms:INCOTERM_FOB); the origin and destination,port_of_loading,port_of_dischargeandcargo_ready_datework as on shipments. - Deprecated: the typed filters of these two lists.
filter.status,filter.etdandfilter.etaonGET /v1/shipment, andfilter.statusandfilter.cargo_ready_dateonGET /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_HOLDisfilter=status = STATUS_ACTIVE OR status = STATUS_ON_HOLD,filter.etd=gte:2026-07-01isfilter=etd >= "2026-07-01", andfilter.eta=2026-07-01..2026-07-31isfilter=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_feedescription of invoices, thedropoff_terminal_codedescriptions 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. TheX-Cargoplot-Keyheader and theCargoplotKeysecurity 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.jsonnow reportswrite_rate_limit. While it is enabled, writes (anything other thanGET,HEADandOPTIONS) are counted against it instead of the shared allowance, and a write over it gets429withAPI 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
searchparameter ofGET /v1/shipmenthas 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
referencefields 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/inquiryraises one for your organization and answers201with the inquiry asGET /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, andfclorlclto 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: trueamong 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 answers200with the whole inquiry. A list, an address andinsured_goods_valueare each replaced by what you send; insidefclandlcleach 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}/cancelwithdraws an inquiry and answers200with it inSTATUS_CANCELLED; reopening one stays in the app.DELETE /v1/inquiry/{inquiry}answers204and takes the inquiry out of your list and reads, so deleting it again answers404. - What a refusal looks like. A request that breaks rules answers
400with agoogle.rpc.BadRequestindetails: 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 asstatus, answers400naming it inmessage. Once a quote has been accepted, every write except a change todescriptionalone answers409. An inquiry in another organization answers404, as it does for the reads. - Corrected: cargo component dimensions are centimetres. The reference
described
width,heightanddepthon 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_SHIPPERand 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
externalDocspoints 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}/trackingreturns 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:seaholds one entry per container, each with its own events;airholds one overall status and one list of events, because air cargo has no container to hang milestones on.etdandetasit 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, andcargosays 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 return400.
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/invoicelists your organization's invoices, andGET /v1/shipment/{shipment}/invoicenarrows 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}/downloadreturns 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}/documentreturns a shipment's document checklist: every slot, with the uploaded file where there is one. A slot with nodocumentmember 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}/downloadreturns an uploaded file, with the content type it was stored as. The id is thedocument.idfrom the checklist, not the slot id.- The checklist covers the document types this API serves.
- Fixed:
GET /v1/inquirysorted byreferenceorcargo_ready_datedropped 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 bystatusorcreate_timewas never affected, and no other endpoint was. - The money schema is now named
apiV1Moneyin the spec, where it wasv1Money. 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 inquiryinsured_goods_valuefields point at the new name too. - Fixed: the documented media types for
MEDIA_TYPE_DOCXandMEDIA_TYPE_XLSXwere each other's — DOCX was documented as Excel'sapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetand 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
DocumentMediaTypeon 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-Keyheader. - 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.comin production, and whatever/api-info.jsonreports asbase_urlin any other environment. /openapi.jsonnow 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 carriedbasePath: /apiand no host, which left the host to be guessed.- Every rate-limited response carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset, so you can pace yourself instead of discovering the ceiling by hitting it.RateLimit-Resetcounts seconds from now, not a timestamp. A 429 still carriesRetry-Afteras well, which answers the narrower question of when to retry this request. - Every description in
/openapi.jsondocuments 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.