Creating and updating inquiries
An inquiry is a request for a price. Four endpoints let an integration raise one and look after it:
| Operation | Endpoint | Answers |
|---|---|---|
| Create | POST /v1/inquiry | 201 with the inquiry |
| Update | PATCH /v1/inquiry/{inquiry} | 200 with the inquiry |
| Cancel | POST /v1/inquiry/{inquiry}/cancel | 200 with the inquiry |
| Delete | DELETE /v1/inquiry/{inquiry} | 204, no body |
{inquiry} takes the Cargoplot reference or the numeric id, as the reads do.
Every answer that carries an inquiry renders it exactly as
GET /v1/inquiry/{inquiry} does, so one parser handles both.
A request body uses the names and types of the inquiry you read. What only
Cargoplot sets is left out: id, reference, status, create_time,
update_time, requester_user_id, organization_id, total_volume and
total_weight. Sending one of them is refused, as is any other key the request
does not have, so a typo such as carrier fails loudly instead of being ignored.
Creating an inquiry
curl -X POST 'https://api.cargoplot.com/v1/inquiry' \
-H 'X-Cargoplot-Key: <token>' \
-H 'Content-Type: application/json' \
-d @inquiry.json
{
"description": "20 pallets of coffee",
"client_references": ["S05749"],
"origin": {
"region_code": "NL",
"locality": "Rotterdam",
"address_lines": ["Wilhelminakade 123"]
},
"destination": { "region_code": "DE", "locality": "Hamburg" },
"cargo_ready_date": "2026-11-02",
"cargo_type": "CARGO_TYPE_PALLETS",
"transport_modes": ["TRANSPORT_MODE_ROAD"],
"incoterms": ["INCOTERM_FCA"],
"lcl": {
"components": [
{ "width": 120, "height": 150, "depth": 80, "weight": 250, "quantity": 4 }
]
}
}
The answer is the new inquiry, shortened here:
{
"id": "1652",
"status": "STATUS_RECEIVED",
"reference": "C69M-DFR7",
"description": "20 pallets of coffee",
"client_references": ["S05749"],
"cargo_ready_date": "2026-11-02",
"cargo_type": "CARGO_TYPE_PALLETS",
"hs_code_count": 1,
"total_volume": 5.76,
"total_weight": 1000,
"lcl": {
"components": [
{ "width": 120, "height": 150, "depth": 80, "weight": 250, "quantity": 4 }
],
"tail_lift": false,
"pallet_exchange": false
}
}
A new inquiry starts in STATUS_RECEIVED. Creating it gathers no prices, and the
answer carries none. Its prices and quotes are listed at
GET /v1/inquiry/{inquiry}/quotes; see quotes. That version covers
normal goods only.
What a create needs
description.originanddestination, each with aregion_code(ISO 3166-1 alpha-2, such asNL) and alocality, the city.cargo_ready_date, the date the cargo can be collected, asYYYY-MM-DD. It has to be a date that exists:2026-02-31is refused.cargo_type, which also decides the shape of the cargo.- At least one
transport_modesentry and at least oneincotermsentry, each given once. Incoterms are a list because each one is priced on its own. - The cargo, in the branch that matches
cargo_type:
cargo_type | Branch | What it needs |
|---|---|---|
CARGO_TYPE_CONTAINERS | fcl | At least one entry in containers, each with a type and a quantity above zero |
CARGO_TYPE_PALLETS, CARGO_TYPE_PACKAGES | lcl | At least one entry in components, each with a width, height and depth in centimetres, a weight in kilograms and a quantity, all above zero |
A container can also name a dropoff_terminal_code, the carrier's code for the
terminal it is dropped off at. An inquiry read back, and a
quote's details, add that terminal's
dropoff_address when we have it, and null otherwise. It is ignored on a
request: send the terminal code.
Send only the branch that matches. For an inquiry created here, total_volume
(cubic metres) and total_weight (kilograms) are computed from the components; a
container inquiry has neither.
Everything else is optional, and leaving it out gives what the app's inquiry form
gives when it is left untouched: false for an option, an empty list for a
filter, 0 for a limit. max_transit_days of 0 means no limit, and
hs_code_count of 0 means one.
A few options only mean something for one kind of cargo, and setting one that does not fit is refused rather than ignored:
storageandtimeslot_deliveryare for pallets and packages.side_loader_deliveryis for containers.tail_liftandpallet_exchangesit insidelcl;min_free_demurrage_daysandmin_free_detention_daysinsidefcl.
The ports are UN/LOCODEs (NLRTM), carriers are SCAC codes, and
insured_goods_value is an amount in the currency's minor unit:
{ "currency": "EUR", "amount_cents": 150000 } is €1,500.00.
client_references are your own order or purchase-order numbers, such as
S05749, so you can link the inquiry and its shipment to your orders exactly.
A list holds at most 20, each 1 to 64 characters once surrounding whitespace is
trimmed, and none twice; they are stored as written, case included, and a
filter finds them whole. On an update the list
you send replaces the stored one.
The vocabularies — cargo types, transport modes, container types, special
contents, Incoterms — are the ones in the glossary, sent by name.
One exception: TRANSPORT_MODE_BARGE cannot be requested on an inquiry yet, and
is refused.
Leaving out parts of the transport
We quote and arrange every part of the transport the incoterm leaves to us. When
you arrange a part yourself, such as the delivery from the port, name it in
excluded_stages: the prices leave it out, and a shipment booked from one of them
has no partner for it. It is what the stage checkboxes on the app's inquiry form do.
{
"incoterms": ["INCOTERM_FOB"],
"excluded_stages": ["STAGE_GROUP_DELIVERY"]
}
The parts are the stage groups. Which of them an incoterm leaves to us:
| Incoterm | Parts left to us |
|---|---|
EXW, DAP, DPU, DDP, CPT, CIP | All six |
FCA | Main carriage (from the handling at the named place on), destination handling, import clearance, delivery |
FAS | Export clearance (only the loading at the port), main carriage, destination handling, import clearance, delivery |
FOB | Main carriage, destination handling, import clearance, delivery |
CFR, CIF | Destination handling, import clearance, delivery |
- One incoterm.
excluded_stagesneeds exactly oneincotermsentry, because each incoterm leaves a different part of the transport to us. With several it answers400, and so does changingincotermsto several while parts are left out. - The main carriage stays.
STAGE_GROUP_MAIN_CARRIAGEis refused, and so is leaving out all three parts aCFRorCIFinquiry leaves to us: nothing would be left to quote. So is changingincotermstoCFRorCIFwhile the inquiry already leaves out all three, as anEXWinquiry may. - A part the incoterm already leaves out is accepted and changes nothing,
such as
STAGE_GROUP_PICKUPunderFOB. It is not echoed back. - Under
FCAexport clearance is the seller's, and the API leaves it out. The app's form can add it to anFCAinquiry; the API cannot, and a write toexcluded_stages, or toincotermswith a different incoterm, removes it. - The answer echoes the parts left out in
excluded_stages. An inquiry whose stages were chosen in the app shows the parts its choice leaves out, and nothing else of it. - On an update,
excluded_stagesreplaces what was left out, and[]drops it. An update that changes onlyincotermskeeps the parts the inquiry echoes and applies them to the new incoterm. A part the old incoterm already left out is not echoed, so it is not carried over: sendexcluded_stagestogether withincotermsto be sure. Changing the incoterm in the app instead resets the inquiry to everything the new incoterm leaves to us. - When the kept parts do not fit the new incoterms, because you send several
incoterms or because they leave a
CFRorCIFinquiry nothing, the update answers400onincoterms. Its description names the parts left out, which may include ones chosen in the app, and the way out: sendexcluded_stagestogether withincoterms, with[]to drop them. For example:the inquiry leaves out STAGE_GROUP_DELIVERY, so it needs exactly one incoterm; send excluded_stages with incoterms (an empty list drops them). When your update carriesexcluded_stagesitself, the400is onexcluded_stages, as for a create. - Prices follow, stored quotes do not. Generated prices are worked out again
for what is left. A quote our team prepared earlier keeps what it covers, so
compare its
covered_stageswith the inquiry'sexcluded_stagesbefore you book it.
A retried create
Nothing extra is needed to make a create safe to retry. If an identical request
from your organization arrives within ten minutes of the first, it creates
nothing: the answer is the same 201 with the inquiry the first request made,
and the response carries Idempotent-Replayed: true so you can tell.
Identical means the same content, not the same bytes. Key order, whitespace, and sending a default explicitly rather than leaving it out do not make two requests different.
- After ten minutes, the same body creates a new inquiry. That is how you copy one.
- An inquiry you have since cancelled or deleted is never replayed; the same body creates a new one.
- Two identical inquiries within ten minutes on purpose are one inquiry
answered twice. Change something that tells them apart, such as the
description.
A refused request stores nothing, so once you have fixed it, sending it again is a fresh create.
An Idempotency-Key makes a retry certain to take
effect once, after ten minutes too, for as long as the key is kept. It does not
tell two identical creates apart: within ten minutes they are still one inquiry,
whatever keys they carry.
Updating an inquiry
PATCH changes the fields the body carries and leaves the rest alone. Which
fields those are is read from the keys you send, so there is nothing else to
supply:
curl -X PATCH 'https://api.cargoplot.com/v1/inquiry/C69M-DFR7' \
-H 'X-Cargoplot-Key: <token>' \
-H 'Content-Type: application/json' \
-d '{ "cargo_ready_date": "2026-11-09", "carriers": ["MAEU", "CMDU"] }'
The answer is the whole inquiry as it now stands.
- A list, an address and
insured_goods_valueare each one value, replaced by what you send, so send them complete. Anoriginsent without apostal_codeleaves the inquiry without one; acomponentslist replaces every component. fclandlclonly group their fields, so each key inside them changes on its own.{ "fcl": { "min_free_demurrage_days": 7 } }changes that number and leaves the containers as they are.- An empty value clears a field:
"port_of_loading": "","carriers": []. A field a create requires cannot be cleared, and answers400. - No update can leave an inquiry without cargo. An empty
containersorcomponentslist, or a bare"lcl": {}, is refused. - Switching
cargo_typebetween containers and pallets or packages needs the new kind of cargo in the same request, since an inquiry for containers cannot keep pallets as its cargo. The options of the kind it leaves are cleared with it:tail_liftandpallet_exchangeon a switch to containers, the free-day counts on a switch away. Pallets to packages keeps the components. - The rules are judged against the inquiry you would end up with, not only
the body.
{ "storage": true }on a container inquiry is refused, although the body says nothing about containers.
Repeating an update is harmless: the second one leaves the inquiry as the first
did, apart from its update_time, which every update moves and which
keeping a copy in sync reads.
Cancelling and deleting
POST /v1/inquiry/{inquiry}/cancel withdraws an inquiry: it answers 200 with
the inquiry in STATUS_CANCELLED, and no quote will follow. A cancelled inquiry
stays in your list and can still be read. Reopening one is done in the app, not
over the API. Cancelling an inquiry that is already cancelled changes nothing and
answers 200 again.
DELETE /v1/inquiry/{inquiry} answers 204 with no body and takes the inquiry
out of your inquiries: it is no longer listed and no longer readable. It is not
erased from Cargoplot's records. Deleting it again answers 404, since there is
nothing left for you to see — so a retried delete that gets a 404 has
succeeded.
Once a quote is accepted
An accepted quote fixes the inquiry, because a shipment is being built from it.
From then on, every write answers 409 — update, cancel and delete alike — with
one exception: a PATCH that changes only the description.
The shipment starts with the inquiry's client_references, and from then on
they are kept on the shipment: change them with
PATCH /v1/shipment/{shipment}. The inquiry
keeps the ones it had.
When a write is refused
| Status | Why |
|---|---|
400 | A field breaks a rule, or the body has a key the request does not have |
404 | No inquiry with that reference or id in your organization |
409 | A quote has been accepted, see above |
A rule broken by a field answers with a google.rpc.BadRequest naming the field
and why, one entry per problem, and every rule the body breaks is in the same
answer. An unknown key is named in message instead. The errors page
shows both shapes in full and says which failures are worth retrying.