Wilson by Cartage
Try Wilson →

API reference

Cartage API

Cartage's public API lets customers programmatically create and retrieve shipments, quotes, sales orders, vendors, products, and address book entries.

Authentication

All endpoints require an organization API key, passed in the X-API-Key request header. Keys are issued per organization—contact support@cartage.ai to obtain one.

Every request must also include your orgId:

  • GET requests: as a query parameter (?orgId=YOUR_ORG_ID)
  • POST/PATCH/PUT/DELETE requests: in the JSON request body

Errors

The API returns standard HTTP status codes:

  • 200 — Success
  • 400 — Missing or invalid orgId, or invalid request input
  • 401 — Missing X-API-Key header, or invalid API key
  • 404 — Organization or document not found (v2 endpoints add a stable code, e.g. QUOTE_NOT_FOUND)
  • 409 —
    • POST /p/v2/shipment: a shipment with that referenceNumber already exists.
    • GET /p/v2/quote and GET /p/v2/salesOrder by referenceNumber: more than one document shares it — read by id.
    • POST /p/v2/addressBook: an entry already exists at that place (ADDRESS_BOOK_PLACE_EXISTS), or another write to it is in progress (ADDRESS_BOOK_PLACE_BUSY; retry)
  • 422 — POST on v2 endpoints: the document is missing a required field (code: "REQUIRED_FIELDS_MISSING", with an issues[] list of { field, code, message })
  • 500 — Server error

Shared rules for /p/v2 document endpoints

Six document types — shipment, quote, salesOrder, vendor, product, addressBook — each have a GET and a POST at /p/v2/<type>. These rules apply to all of them; each endpoint page lists only what is specific to its type.

  • Create body: { "orgId": "…", "<type>": { … }, "activityLog": { "action": "…", "details": "…" } }. activityLog is optional and defaults to { "action": "Created via API" }.
  • Create response: 200 with { "status": "CREATED", "<type>": { … } }, the document in the same shape GET returns. An advisories array of { field, code, message } is added when the create succeeded but something is worth knowing, such as a linked id that matched nothing and was dropped (UNKNOWN_LINKED_IDS_DROPPED).
  • Required fields: each page has a Required fields table. A missing one is a 422 that lists every gap at once.
  • Unknown fields are refused: a top-level field that is not in the page's schema is a 400 naming it. So are fields the API sets itself: id, orgId inside the document, createdAt, updatedAt, markdownContent, the document's own activityLog, and computed fields.
  • Nothing is written on a 400, 409 or 422. Fix the body and resend.
  • Duplicate checks on shipment and addressBook only. shipment refuses a repeated referenceNumber; addressBook refuses a second entry at the same place. On the other four types, sending the same POST twice creates two documents, so store the id you get back.
  • Reads: only populated fields are returned. markdownContent is never returned. A document that belongs to another organization answers the same 404 as one that does not exist.
  • Formats: timestamps are ISO 8601. Money is in major units (575 is $575.00).

Error body

{
    "error": "Human-readable message",
    "code": "STABLE_CODE",
    "issues": [
        { "field": "path.to.field", "code": "STABLE_CODE", "message": "What is wrong." }
    ]
}

error is always present. code is on 404, 409 and 422. A 409 can carry extra fields for that refusal, such as existingAddressBookId. issues is on 400 and 422. Branch on code, never on the error text.

Shared objects

  • Money: { amount, currency }. amount is required. currency is usd or cad and defaults to usd.
  • Weight: { value, unit }, both required. unit is lbs, kg, oz or tons.
  • Dimensions: { length, width, height, lengthUnit, widthUnit, heightUnit }. Units are in, cm, ft, m or mm. Every value you send needs its unit.
  • Address: name, address1, address2, city, state, zipCode, country, placeId, coordinates ({ latitude, longitude }), timezone (IANA), businessHoursStartAt / businessHoursEndAt (HH:mm), firstName, lastName, contactName, contactEmail, phoneNumber, phoneNumberExt, unLocode, rampCode, addressBookId.
  • Contact: fullName, firstName, lastName, email, phone, phoneExt, title, company.
  • Activity log entry (read-only, in every document's activityLog): { action, details, timestamp, source }.

Endpoints

  • Shipment: Read a shipment by reference number, or create one, with GET and POST /p/v2/shipment.
  • Quote: Read a carrier quote by id or reference number, or create one, with GET and POST /p/v2/quote.
  • Sales order: Read a sales order by id or reference number, or create one, with GET and POST /p/v2/salesOrder.
  • Vendor: Read a vendor by id, or create one, with GET and POST /p/v2/vendor.
  • Product: Read a product by id, or create one, with GET and POST /p/v2/product.
  • Address book: Read an address book entry by id, or create one, with GET and POST /p/v2/addressBook.
  • Get rates: Get instant FTL and LTL rate predictions and quotes with POST /p/getRates.

Questions? Email support@cartage.ai

Last updated October 7th, 2026 (v1.2)