Cargoplot APICargoplot API
API docs
OpenAPI spec

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:

GET
/v1/inquiry/C3AT-XHM0/quotes
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

json
{
  "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.

FieldMeaning
idIdentifies the price or quote. Opaque, see the id
inquiry_idThe numeric id of the inquiry it is for
statusWhere it stands, see the glossary
recommendedtrue when our team recommends this quote
total_ex_vat, total_inc_vatThe totals, in EUR, as money: amount_cents is in cents
total_estimatedtrue 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_tillThe first and the last day the price applies, as YYYY-MM-DD
carriersThe 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_dischargeThe ports, as UN/LOCODEs such as NLRTM, as on the inquiry
transport_modeHow the cargo travels, such as TRANSPORT_MODE_SEA
min_transit_days, max_transit_daysThe 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_daysThe free days of demurrage, of detention, and of both combined
incotermThe delivery terms the price is for, such as INCOTERM_FOB
free_storage_daysThe free days of storage
covered_stagesThe 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.

GET
/v1/quote/{quote}/details
curl -H 'X-Cargoplot-Key: <token>' \
  'https://api.cargoplot.com/v1/quote/cXV0ZS0xMjM0NQ/details'
json
{
  "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.

FieldMeaning
referenceOur reference for a quote our team prepared. Absent on a worked-out price
origin, destinationWhere the price starts and ends, as addresses
published_atWhen it was published. A worked-out price is dated by day, so its time is midnight UTC
cargo_typeWhat kind of cargo it is for, which decides whether containers or components lists it
total_weight, total_volumeThe weight of the cargo in kilograms and its volume in cubic metres
containersFor a container price: each container's type, quantity, the drop-off terminal's dropoff_terminal_code and that terminal's dropoff_address
componentsFor pallets and packages: each unit's dimensions in centimetres, weight in kilograms and quantity
line_itemsThe charges, in the order the app shows them, see below
agent_feeCargoplot's fee, in EUR, which the totals include. Negative when it is a discount, 0 when there is none
vatThe VAT per currency, category and rate, as it was calculated, sorted by currency, category and rate
subtotals_per_currencyThe charges excluding VAT summed per currency, sorted by currency, see below
notesRemarks on the price or quote, see below
vat_reverse_chargedtrue 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

StatusWhy
403Prices are not available to your account. Contact Cargoplot to have them made available
404No 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
429The 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:

GET
/v1/quote/{quote}/sailings
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.

json
{
  "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": {}
}
FieldMeaning
sailingThe sailing as the booking takes it: carrier_scac, carrier_name, vessel and etd. Pass it unchanged
bookabletrue when the sailing can still be chosen when booking, see below
cut_off_timeThe carrier's cut-off for the sailing
etaThe expected arrival at the last port it reaches by sea
transit_daysThe transit time, in days, as the carrier schedules it
departure_port, arrival_portThe ports it departs from and arrives at by sea
schedule_retrieve_timeWhen 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

StatusWhy
400A parameter is malformed or out of range, or the cursor does not belong to this quote
403Prices are not available to your account. Contact Cargoplot to have them made available
404No 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
429The quote allowance is used up. See rate limits

Booking a quote

One POST books the price or quote an id names:

POST
/v1/quote/{quote}/accept
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:

json
{
  "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:

json
{
  "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

StatusWhy
400The body is malformed, carries an unknown key, or preferred_sailings breaks one of the rules above
403Prices are not available to your account. Contact Cargoplot to have them made available
404No 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
409The 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
429The quote allowance is used up. See rate limits

Sorting

order_by chooses the order:

order_byLists first
QUOTE_ORDER_BY_RECOMMENDEDThe default. Sailings with a reliable schedule and few expected delays, then the lowest total_ex_vat
QUOTE_ORDER_BY_CHEAPESTThe lowest total_ex_vat
QUOTE_ORDER_BY_FASTESTThe earliest expected arrival of the first sailing that can still be booked
bash
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_vat stays, and on an equal price the quote prepared by our team does. The recommended flag 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_till has passed can be listed as well. valid_till is 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_vat equals its total_ex_vat and total_estimated is true. Nothing is hidden and nothing fails; compare such a price on total_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.

bash
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

StatusWhy
400A parameter is malformed or out of range, or the cursor does not belong to this request
403Prices are not available to your account. Contact Cargoplot to have them made available
404No inquiry with that reference or id in your organization
429The quote allowance is used up. See rate limits

The errors page shows the shape of each answer and says which failures are worth retrying.