Cargoplot APICargoplot API
API docs
OpenAPI spec

Creating and updating inquiries

An inquiry is a request for a price. Four endpoints let an integration raise one and look after it:

OperationEndpointAnswers
CreatePOST /v1/inquiry201 with the inquiry
UpdatePATCH /v1/inquiry/{inquiry}200 with the inquiry
CancelPOST /v1/inquiry/{inquiry}/cancel200 with the inquiry
DeleteDELETE /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

POST
/v1/inquiry
curl -X POST 'https://api.cargoplot.com/v1/inquiry' \
  -H 'X-Cargoplot-Key: <token>' \
  -H 'Content-Type: application/json' \
  -d @inquiry.json
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:

json
{
  "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.
  • origin and destination, each with a region_code (ISO 3166-1 alpha-2, such as NL) and a locality, the city.
  • cargo_ready_date, the date the cargo can be collected, as YYYY-MM-DD. It has to be a date that exists: 2026-02-31 is refused.
  • cargo_type, which also decides the shape of the cargo.
  • At least one transport_modes entry and at least one incoterms entry, 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_typeBranchWhat it needs
CARGO_TYPE_CONTAINERSfclAt least one entry in containers, each with a type and a quantity above zero
CARGO_TYPE_PALLETS, CARGO_TYPE_PACKAGESlclAt 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:

  • storage and timeslot_delivery are for pallets and packages.
  • side_loader_delivery is for containers.
  • tail_lift and pallet_exchange sit inside lcl; min_free_demurrage_days and min_free_detention_days inside fcl.

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.

json
{
  "incoterms": ["INCOTERM_FOB"],
  "excluded_stages": ["STAGE_GROUP_DELIVERY"]
}

The parts are the stage groups. Which of them an incoterm leaves to us:

IncotermParts left to us
EXW, DAP, DPU, DDP, CPT, CIPAll six
FCAMain carriage (from the handling at the named place on), destination handling, import clearance, delivery
FASExport clearance (only the loading at the port), main carriage, destination handling, import clearance, delivery
FOBMain carriage, destination handling, import clearance, delivery
CFR, CIFDestination handling, import clearance, delivery
  • One incoterm. excluded_stages needs exactly one incoterms entry, because each incoterm leaves a different part of the transport to us. With several it answers 400, and so does changing incoterms to several while parts are left out.
  • The main carriage stays. STAGE_GROUP_MAIN_CARRIAGE is refused, and so is leaving out all three parts a CFR or CIF inquiry leaves to us: nothing would be left to quote. So is changing incoterms to CFR or CIF while the inquiry already leaves out all three, as an EXW inquiry may.
  • A part the incoterm already leaves out is accepted and changes nothing, such as STAGE_GROUP_PICKUP under FOB. It is not echoed back.
  • Under FCA export clearance is the seller's, and the API leaves it out. The app's form can add it to an FCA inquiry; the API cannot, and a write to excluded_stages, or to incoterms with 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_stages replaces what was left out, and [] drops it. An update that changes only incoterms keeps 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: send excluded_stages together with incoterms to 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 CFR or CIF inquiry nothing, the update answers 400 on incoterms. Its description names the parts left out, which may include ones chosen in the app, and the way out: send excluded_stages together with incoterms, 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 carries excluded_stages itself, the 400 is on excluded_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_stages with the inquiry's excluded_stages before 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:

PATCH
/v1/inquiry/C69M-DFR7
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_value are each one value, replaced by what you send, so send them complete. An origin sent without a postal_code leaves the inquiry without one; a components list replaces every component.
  • fcl and lcl only 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 answers 400.
  • No update can leave an inquiry without cargo. An empty containers or components list, or a bare "lcl": {}, is refused.
  • Switching cargo_type between 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_lift and pallet_exchange on 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

StatusWhy
400A field breaks a rule, or the body has a key the request does not have
404No inquiry with that reference or id in your organization
409A 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.