API reference

Quote

https://v2.cartage.ai/p/v2/quote reads (GET) and creates (POST) quotes.

A quote is a carrier's rate for one or more shipments. The quoteIds on a shipment point at quotes.

Authentication, the create envelope, error format and shared objects are in Shared rules.

GET /p/v2/quote

Read one quote by id or by referenceNumber. Send exactly one of the two.

Parameter	Required	Description
`orgId`	Yes	Your organization ID
`id`	One of the two	Quote id, for example a value from a shipment's `quoteIds`
`referenceNumber`	One of the two	Quote reference, for example `QTE-0007`

curl "https://v2.cartage.ai/p/v2/quote?orgId=<yourOrgId>&id=<quoteId>" \
  -H "X-API-Key: <yourApiKey>"

Returns the quote (see Schema).

POST /p/v2/quote

Create one quote. It is linked onto every shipment in shipmentIds and shows up in that shipment's quotes.

Required fields

Field	Required	If missing
`shipmentIds`	Always. An array; may be `[]` only if you send `stops`.	`400`
`serviceType`	Always	`422` `QUOTE_SERVICE_TYPE`
`baseCharge.amount`	Always	`422` `QUOTE_BASE_CHARGE`
A lane: a shipment id in `shipmentIds`, or `stops` with an origin and a destination	Always, one of the two	`422` `QUOTE_LANE`
`vendorId`	Only when `status` is `accepted`	`422` `QUOTE_ACCEPTED_VENDOR`
`stops[].sequenceNumber`; `commodities[].id` and `.name`; `accessorialCharges[].name` and `.amount`	On every entry you send	`400`

Smallest valid quote:

Linked to a shipment: { "shipmentIds": ["<shipmentId>"], "serviceType": "ltl", "baseCharge": { "amount": 575 } }
With its own lane: { "shipmentIds": [], "serviceType": "ltl", "baseCharge": { "amount": 575 }, "stops": [ { "sequenceNumber": 0, "city": "Chicago", "state": "IL" }, { "sequenceNumber": 1, "city": "Detroit", "state": "MI" } ] }

A shipment id that is not in your organization is dropped and reported in advisories. If that leaves no lane, the create is refused with QUOTE_LANE.

Leave referenceNumber out and one is created for you (QTE-####). Reference numbers are not checked for duplicates. If two quotes share one, read them by id.

Example

curl -X POST "https://v2.cartage.ai/p/v2/quote" \
  -H "X-API-Key: <yourApiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<yourOrgId>",
    "quote": {
      "shipmentIds": ["<shipmentId>"],
      "carrierName": "TQL",
      "serviceType": "ltl",
      "transitDays": 3,
      "baseCharge": { "amount": 575 },
      "fuelSurcharge": { "amount": 85 },
      "accessorialCharges": [ { "name": "liftgate", "amount": 45 } ],
      "notes": "Rate valid 7 days."
    }
  }'

{
    "status": "CREATED",
    "quote": {
        "id": "qte_123",
        "referenceNumber": "QTE-0007",
        "status": "pending",
        "totalRate": { "amount": 705, "currency": "usd" },
        "…": "…"
    }
}

Errors

Status	Code	Meaning and fix
400	—	On `GET`, missing `orgId`, or both or neither of `id` and `referenceNumber`. On `POST`, a missing `shipmentIds`, a wrong type, an unknown enum value, or a field not in the Schema (including the read-only fields below). `issues[]` names each one.
401	—	Missing or invalid API key
404	`QUOTE_NOT_FOUND`	No matching quote in your organization
409	`QUOTE_REFERENCE_NUMBER_AMBIGUOUS`	`GET` only. More than one quote has that `referenceNumber`. Read the one you mean by `id`.
422	`REQUIRED_FIELDS_MISSING`	A required field is missing. Each `issues[]` entry carries one of the codes in Required fields.

Schema

Optional unless marked Required. id, orgId, createdAt, updatedAt and activityLog are returned on every quote and cannot be sent.

Field	Type	Description
`shipmentIds`	string[]	Required. Shipments this quote is for
`serviceType`	enum	Required. `ftl` \| `ltl` \| `drayage` \| `rail` \| `ocean` \| `air` \| `lastMile` \| `parcel` \| `willCall`
`baseCharge`	Money	Required. Line-haul charge
`vendorId`	string	Required when `accepted`. The carrier's vendor id
`stops`	object[]	Required if `shipmentIds` is empty. Route, in order. Each is an Address plus a required `sequenceNumber` (0 = origin).
`referenceNumber`	string	Created as `QTE-####` if left out
`status`	enum	`pending` (default) \| `accepted` \| `rejected` \| `expired`
`fuelSurcharge`	Money	Fuel surcharge
`accessorialCharges`	object[]	`{ name, amount, currency }` each. `name` is an accessorial such as `liftgate`, `insideDelivery`, `residentialDelivery`, `limitedAccess`, `appointmentRequired`, `hazmat`.
`vendorName`	string	Vendor name
`carrierName` / `carrierScac`	string	Carrier and its SCAC
`serviceName`	string	The carrier's own service label, such as `Standard`
`transitDays`	number	Quoted transit days
`distance` / `distanceUnit`	number / enum	Route distance, `mi` or `km`
`commodities`	object[]	Freight the rate covers. Each needs `id` and `name`; also takes `quantity`, `unitWeight`, `totalWeight`, `dimensions`, `freightClass`, `nmfcItemCode`.
`transshipmentPorts`	string[]	Ocean and air: ports in between, when the routing is not direct
`notes`	string	Validity, conditions, carrier remarks
`fileIds`	string[]	Attached files

Read-only fields

Returned, never sent.

Field	Type	Description
`origin` / `destination`	object	First and last stop
`totalRate`	Money	Base, fuel and accessorials added up
`platform` / `index` / `quotedAt`	string / number / string	Set when Cartage priced the quote itself