Quotes
Once an inquiry has been priced, one endpoint lists what it can be booked at, one shows the details of each, one lists the sailings each can be booked on, and one books it:
curl -H 'X-Cargoplot-Key: <token>' \
'https://api.cargoplot.com/v1/inquiry/C3AT-XHM0/quotes'
{inquiry} takes the Cargoplot reference or the numeric id, as the other
inquiry endpoints do. Only an inquiry of your organization can be listed.
One list holds two kinds of record, in the same shape: the prices worked out for the inquiry, and the quotes our team prepared for it. A response does not tell you which is which, and it does not need to: both are read, sorted and booked the same way — see booking a quote.
This version covers normal goods only. Prices and quotes restricted to a single commodity are not listed.
A record
{
"quotes": [
{
"id": "cXV0ZS0xMjM0NQ",
"inquiry_id": "1652",
"status": "QUOTE_STATUS_PUBLISHED",
"recommended": true,
"total_ex_vat": { "currency": "EUR", "amount_cents": 184250 },
"total_inc_vat": { "currency": "EUR", "amount_cents": 222943 },
"total_estimated": false,
"valid_from": "2026-11-01",
"valid_till": "2026-11-30",
"carriers": [{ "scac": "MAEU", "name": "Maersk" }],
"port_of_loading": "SGSIN",
"port_of_discharge": "NLRTM",
"transport_mode": "TRANSPORT_MODE_SEA",
"min_transit_days": 28,
"max_transit_days": 35,
"free_demurrage_days": 7,
"free_detention_days": 7,
"free_dd_combined_days": 0,
"incoterm": "INCOTERM_FOB",
"free_storage_days": 0,
"covered_stages": [
"STAGE_GROUP_MAIN_CARRIAGE",
"STAGE_GROUP_DESTINATION_HANDLING",
"STAGE_GROUP_IMPORT_CLEARANCE",
"STAGE_GROUP_DELIVERY"
]
}
]
}
The answer is shortened here to one record, and carries a cursor when there is
more, as the other lists do.
| Field | Meaning |
|---|---|
id | Identifies the price or quote. Opaque, see the id |
inquiry_id | The numeric id of the inquiry it is for |
status | Where it stands, see the glossary |
recommended | true when our team recommends this quote |
total_ex_vat, total_inc_vat | The totals, in EUR, as money: amount_cents is in cents |
total_estimated | true when some of the price is in another currency, so the EUR totals are an estimate: converted, or left unconverted when we have no rate |
valid_from, valid_till | The first and the last day the price applies, as YYYY-MM-DD |
carriers | The shipping lines it is tied to, each with a scac and, when known, a name. Empty when it is not tied to one |
port_of_loading, port_of_discharge | The ports, as UN/LOCODEs such as NLRTM, as on the inquiry |
transport_mode | How the cargo travels, such as TRANSPORT_MODE_SEA |
min_transit_days, max_transit_days | The shortest and the longest transit time, in days, across the sailings it can be booked on |
free_demurrage_days, free_detention_days, free_dd_combined_days | The free days of demurrage, of detention, and of both combined |
incoterm | The delivery terms the price is for, such as INCOTERM_FOB |
free_storage_days | The free days of storage |
covered_stages | The parts of the transport it covers, as stage groups, in the order of the transport |
A value that is not known is absent, not empty. That holds for the validity
dates, the ports, the transport mode and the incoterm when the quote names none, for both
transit times when it has no sailings, and for a carrier's name when no sailing
names it. A carriers entry always has its scac.
The free days are always present, and 0 can mean two things: no free days,
or a quote that does not specify them. It cannot tell you which, so do not read a
0 as a promise that the cargo pays from day one.
covered_stages is read from the quote itself. A part counts as covered
when the quote covers any of its stages. A generated price follows the inquiry's
excluded_stages; a quote our
team prepared keeps what it covered when the inquiry changes, so compare the two
before you book. Who carries out a part is not published.
total_estimated matters when you compare totals. A price that is partly in
another currency has its EUR totals converted, or left unconverted when we have
no rate for it, so treat them as an estimate beside the exact total of a price
that is wholly in EUR.
The id
The id is opaque. Pass it back as you got it, to the endpoints that take a
quote, and never parse one or build one yourself.
A generated price's id changes whenever its price changes, which happens
when rates or exchange rates move. An id you stored last week may no longer
name anything, so list again before you book. An endpoint that takes an id
answers 404 for one that no longer names a listed price.
Details of a quote
One GET returns the full breakdown of the price or quote an id names: what
the app shows under View quote.
curl -H 'X-Cargoplot-Key: <token>' \
'https://api.cargoplot.com/v1/quote/cXV0ZS0xMjM0NQ/details'
{
"quote": {
"id": "cXV0ZS0xMjM0NQ",
"status": "QUOTE_STATUS_PUBLISHED",
"total_ex_vat": { "currency": "EUR", "amount_cents": 184250 },
"total_inc_vat": { "currency": "EUR", "amount_cents": 194225 },
"total_estimated": true
},
"reference": "Q-26-0142",
"origin": { "region_code": "SG", "locality": "Singapore", "address_lines": ["1 Pioneer Road"] },
"destination": { "region_code": "NL", "locality": "Tilburg" },
"published_at": "2026-10-28T09:30:00Z",
"cargo_type": "CARGO_TYPE_CONTAINERS",
"total_weight": 12500,
"total_volume": 33.2,
"containers": [
{
"type": "CONTAINER_TYPE_40_HIGH_CUBE",
"quantity": 2,
"dropoff_terminal_code": "NLRTM-APM2",
"dropoff_address": { "region_code": "NL", "locality": "Rotterdam", "address_lines": ["Europaweg 875"] }
}
],
"components": [],
"line_items": [
{
"description": "Ocean freight",
"quantity": 2,
"unit": "container",
"unit_price": { "currency": "USD", "amount_cents": 75000 },
"price_ex_vat": { "currency": "USD", "amount_cents": 150000 },
"vat_category": "CATEGORY_ZERO",
"vat_rate": 0
},
{
"description": "Delivery to Tilburg",
"quantity": 1,
"unit_price": { "currency": "EUR", "amount_cents": 45000 },
"price_ex_vat": { "currency": "EUR", "amount_cents": 45000 },
"vat_category": "CATEGORY_STANDARD",
"vat_rate": 0.21
}
],
"agent_fee": { "currency": "EUR", "amount_cents": 2500 },
"vat": [
{ "category": "CATEGORY_STANDARD", "rate": 0.21, "amount": { "currency": "EUR", "amount_cents": 9975 } }
],
"subtotals_per_currency": [
{ "currency": "EUR", "amount_cents": 47500 },
{ "currency": "USD", "amount_cents": 150000 }
],
"notes": "Rates valid for sailings until 30 November.\nPeak season surcharge included.",
"vat_reverse_charged": false
}
quote is the record exactly as the list shows it, shortened here.
The details and the list are read from the same listing, so they always agree on
the id, the totals and the terms.
| Field | Meaning |
|---|---|
reference | Our reference for a quote our team prepared. Absent on a worked-out price |
origin, destination | Where the price starts and ends, as addresses |
published_at | When it was published. A worked-out price is dated by day, so its time is midnight UTC |
cargo_type | What kind of cargo it is for, which decides whether containers or components lists it |
total_weight, total_volume | The weight of the cargo in kilograms and its volume in cubic metres |
containers | For a container price: each container's type, quantity, the drop-off terminal's dropoff_terminal_code and that terminal's dropoff_address |
components | For pallets and packages: each unit's dimensions in centimetres, weight in kilograms and quantity |
line_items | The charges, in the order the app shows them, see below |
agent_fee | Cargoplot's fee, in EUR, which the totals include. Negative when it is a discount, 0 when there is none |
vat | The VAT per currency, category and rate, as it was calculated, sorted by currency, category and rate |
subtotals_per_currency | The charges excluding VAT summed per currency, sorted by currency, see below |
notes | Remarks on the price or quote, see below |
vat_reverse_charged | true when a charge is reverse-charged: the VAT on it is accounted for by you, not charged here |
A message that is not set is null, unlike the list, where a
value that is not known is absent. origin, destination, published_at, a
container's dropoff_address, and the amounts of a charge without a currency
are null when there is nothing to show. reference, cargo_type,
total_weight, total_volume, notes and a charge's description and unit
are absent instead, and the lists are empty.
Charges
Each entry of line_items is one charge, with an invoice line's fields:
description, quantity, unit, unit_price and price_ex_vat in the
charge's own currency, and the VAT treatment in
vat_category with its vat_rate. They come in the order the app shows them.
VAT rates are fractions, here and in vat: 0.21 is 21%. The vat rows are
the VAT as it was calculated, rows with a zero amount included, so they need not
add up to anything you could work out from the charges yourself.
subtotals_per_currency sums the charges of each currency, as the app's totals
do, with the agent fee added to the EUR subtotal. There is always an EUR entry,
even when no charge is in EUR. A charge without a currency counts in none. When
some charges are in another currency, quote.total_estimated is true: the EUR
totals were converted, and are an estimate.
Notes
notes and each charge's description are plain text, as written on the
quote, with line breaks as \n. They can contain characters such as < and
&: escape them before you render them as HTML.
When details are refused
| Status | Why |
|---|---|
403 | Prices are not available to your account. Contact Cargoplot to have them made available |
404 | No such price or quote in your organization, or its price has changed since it was listed. List the inquiry's quotes again for its current id. A worked-out price's id changes with its price, and once the inquiry has a booked quote or is cancelled its worked-out prices are no longer listed: their details answer 404 too |
429 | The quote allowance is used up. See rate limits |
Sailings of a quote
One GET lists the sailings the price or quote an id names can be booked on:
curl -H 'X-Cargoplot-Key: <token>' \
'https://api.cargoplot.com/v1/quote/cXV0ZS0xMjM0NQ/sailings'
These are the sailings the app offers for that quote: the departures of its shipping lines from its port of loading to its port of discharge whose cut-off is still ahead (an undated one excepted, see order and paging), narrowed to those that suit the inquiry's cargo-ready date and the quote's validity wherever a shipping line has any that do.
{
"sailings": [
{
"sailing": {
"carrier_scac": "MAEU",
"carrier_name": "Maersk",
"vessel": "MAERSK SELETAR",
"etd": "2026-12-08T06:00:00Z"
},
"bookable": true,
"cut_off_time": "2026-12-05T12:00:00Z",
"eta": "2027-01-09T14:00:00Z",
"transit_days": 32,
"departure_port": "SGSIN",
"arrival_port": "NLRTM",
"schedule_retrieve_time": "2026-10-29T03:15:00Z"
}
],
"cursor": {}
}
| Field | Meaning |
|---|---|
sailing | The sailing as the booking takes it: carrier_scac, carrier_name, vessel and etd. Pass it unchanged |
bookable | true when the sailing can still be chosen when booking, see below |
cut_off_time | The carrier's cut-off for the sailing |
eta | The expected arrival at the last port it reaches by sea |
transit_days | The transit time, in days, as the carrier schedules it |
departure_port, arrival_port | The ports it departs from and arrives at by sea |
schedule_retrieve_time | When this shipping line's schedule for the route was last retrieved |
A time that is not known is null, unlike the list, where a
value that is not known is absent. transit_days and the two ports are absent
when the schedule does not give them.
The ports are the codes the schedule uses. They are usually UN/LOCODEs, but not
always the one the quote uses for the same port: the quote can say CNSGH where
its sailings say CNSHA, both Shanghai.
Which sailings can be booked
bookable is true for a sailing without a cut-off, and for one whose cut-off
falls on or after the later of two days: ten days from today, and three days
after the inquiry's cargo-ready date. A sailing listed with bookable set to
false is shown for reference; booking with it is refused.
Those days are counted in UTC, while the app counts them in your own time
zone, so around midnight the two can disagree by a day.
Sailings change
Sailings are the shipping lines' published schedules, and they change as those do: a cut-off passes, a departure moves, a schedule is refreshed. Read them close to when you book, and do not keep them.
A quote can have no sailings. A price that is not tied to a shipping line has
none, and neither has a quote whose route has no published schedule. The answer
is then an empty list, not an error, and you book that quote without
preferred_sailings.
Order and paging
Sailings are sorted by etd, earliest first, with any that have no departure
date last. On the same etd they are ordered by carrier_scac, carrier_name
and vessel. A sailing without a departure date is listed whatever its cut-off;
bookable still says whether you can choose it.
They page with a cursor, as the other lists do: limit takes 1 to
100 and defaults to 50. A cursor keeps its place when the sailing it was cut at
has gone, but sailings can still appear or drop out between two pages. A cursor
continues only the sailings of the quote it was issued for; used for another
quote, it is refused with a 400, and limit may change.
When sailings are refused
| Status | Why |
|---|---|
400 | A parameter is malformed or out of range, or the cursor does not belong to this quote |
403 | Prices are not available to your account. Contact Cargoplot to have them made available |
404 | No such price or quote in your organization, or its price has changed since it was listed. List the inquiry's quotes again for its current id. Once the inquiry has a booked quote or is cancelled, its worked-out prices are no longer listed, and their sailings answer 404 too |
429 | The quote allowance is used up. See rate limits |
Booking a quote
One POST books the price or quote an id names:
curl -X POST -H 'X-Cargoplot-Key: <token>' \
-H 'Content-Type: application/json' \
'https://api.cargoplot.com/v1/quote/cXV0ZS0xMjM0NQ/accept' \
-d '{}'
The body may be empty, and {} is the whole of it unless you name preferred
sailings. The answer is the booked quote and the shipment the booking created:
{
"quote": {
"id": "cXV0ZS05OTk5OQ",
"status": "QUOTE_STATUS_ACCEPTED",
"total_ex_vat": { "currency": "EUR", "amount_cents": 184250 },
"total_inc_vat": { "currency": "EUR", "amount_cents": 184250 }
},
"shipment_id": 48213
}
quote is the record as the listing shows it from then on, shortened here.
shipment_id is for GET /v1/shipment/{shipment}. The booking
creates the shipment before it answers, so the id is absent only in the rare case
where creating it failed. Cargoplot repairs that — do not book again. A
retry can also arrive while the shipment is
still being created.
A booking is final. The shipment it created takes over from the inquiry, which you can no longer cancel or reopen. To call the booking off, get in touch with your Cargoplot contact about cancelling the shipment.
A booked price gets a new id
When you book one of the prices worked out for the inquiry, we store a copy of
it as a quote and book that copy. The quote in the answer has a new id.
Use that id from then on: the id you booked with no longer names anything. The
copy is stored without VAT, so its total_inc_vat equals its total_ex_vat.
Booking one of the quotes our team prepared keeps the id it was listed under.
Preferred sailings
preferred_sailings says which sailings you would rather have, ranked:
{
"preferred_sailings": [
{
"order": 1,
"sailing": {
"carrier_scac": "MAEU",
"carrier_name": "Maersk",
"vessel": "MAERSK SELETAR",
"etd": "2026-12-08T06:00:00Z"
}
}
]
}
At most two entries, each with a different order of 1 for the first choice or
2 for the second; a single second choice is allowed. Every entry must be one of
that quote's sailings, with bookable set to true;
anything else is refused with 400, naming the preference. Take sailing from
the list as it is. A sailing is identified by all four of carrier_scac, carrier_name,
vessel and etd together, and vessel carries several names joined with |
when the sailing changes vessel on the way.
Two preferences may not name the same carrier and vessel, even on different
departures: that pair is refused with 400 as a duplicate, although the two
sailings are distinct by the rule above. Rank two different vessels, or send one
preference.
Whether a sailing can still be booked depends on its cut-off, as
bookable says. A quote with no sailings is
booked without preferred_sailings, and Cargoplot chooses; leaving the field out
is not a worse booking either way.
Booking the same thing twice
A booking you already made answers again rather than happening twice, but which answer you get depends on what you booked.
A quote our team prepared — booking its id again answers 200 with the
header Idempotent-Replayed: true and the same quote and shipment_id. Preferred
sailings sent with the retry are not acted on, so they change nothing — but they
are still checked against the rules above, so a retry carrying a body that breaks
one is still refused with 400. shipment_id can be absent on a replay that
arrives while the first booking is still creating its shipment.
A price worked out for the inquiry — booking its id again answers 409,
naming the quote the first booking made. Nothing records which price a stored
copy came from, so the second attempt cannot be recognised as the same booking.
Book the id the message names to be told your booking already stands, or list the
inquiry again, where that quote now appears as QUOTE_STATUS_ACCEPTED. To have
the retry answered as the first booking instead, send the same
Idempotency-Key with both.
When a booking is refused
| Status | Why |
|---|---|
400 | The body is malformed, carries an unknown key, or preferred_sailings breaks one of the rules above |
403 | Prices are not available to your account. Contact Cargoplot to have them made available |
404 | No such price or quote in your organization, or its price has changed since it was listed. List the inquiry's quotes again and book the new id |
409 | The inquiry already has a booked quote, is cancelled, the quote is no longer open to booking, or a drop-off location on it is unresolved. Contact Cargoplot for the last of those |
429 | The quote allowance is used up. See rate limits |
Sorting
order_by chooses the order:
order_by | Lists first |
|---|---|
QUOTE_ORDER_BY_RECOMMENDED | The default. Sailings with a reliable schedule and few expected delays, then the lowest total_ex_vat |
QUOTE_ORDER_BY_CHEAPEST | The lowest total_ex_vat |
QUOTE_ORDER_BY_FASTEST | The earliest expected arrival of the first sailing that can still be booked |
curl -G -H 'X-Cargoplot-Key: <token>' \
'https://api.cargoplot.com/v1/inquiry/C3AT-XHM0/quotes' \
--data-urlencode 'order_by=QUOTE_ORDER_BY_CHEAPEST'
Recommended and fastest rank on sailing schedules and on how late sailings are expected to run. While those schedules are not being refreshed, the two orders are less precise than usual. Cheapest does not depend on them.
What is in the list
- Records that differ only in price are listed once. The one with the lower
total_ex_vatstays, and on an equal price the quote prepared by our team does. Therecommendedflag does not tell two records apart either. - Expired prices fill a short list. When an inquiry has fewer than five
current prices, prices whose
valid_tillhas passed can be listed as well.valid_tillis how you tell them apart: check it before you rely on one. - Once the inquiry has a booked quote, or is cancelled, no prices are worked out for it. Only the quotes stored for the inquiry are listed from then on, the booked one among them. There is nothing left to price.
- A price we have no exchange rate for is listed as an estimate. When part of
it is in a currency we cannot convert, its
total_inc_vatequals itstotal_ex_vatandtotal_estimatedistrue. Nothing is hidden and nothing fails; compare such a price ontotal_ex_vat.
Paging
The list pages with a cursor, as the other lists do: see
pagination. limit takes 1 to 100 and defaults to 50, and most
inquiries fit on one page at limit=100.
curl -H 'X-Cargoplot-Key: <token>' \
'https://api.cargoplot.com/v1/inquiry/C3AT-XHM0/quotes?limit=100'
The list is assembled on every request, pages included, from prices that can be
up to a few minutes old. When a price changes, ids and pages can still shift: a
record can move, repeat or drop out between two pages. For a view that holds
together, ask again from no cursor, and ask for limit=100 so that one page is all
there is.
A cursor continues only the listing that returned it. Used for another inquiry or
with another order_by, it is refused with a 400; limit may change.
Start again without a cursor to change either.
When a listing is refused
| Status | Why |
|---|---|
400 | A parameter is malformed or out of range, or the cursor does not belong to this request |
403 | Prices are not available to your account. Contact Cargoplot to have them made available |
404 | No inquiry with that reference or id in your organization |
429 | The quote allowance is used up. See rate limits |
The errors page shows the shape of each answer and says which failures are worth retrying.