Shipments

Create Shipment

POST /v1/shipments

Book a shipment from an existing quote.

Request Body

Field	Type	Required	Description
`quote_id`	number	Yes	ID of the quote to book
`customer_id`	number	No	Customer ID to associate
`ship_from.company`	string	No	Shipper company
`ship_from.contact`	string	No	Shipper contact name
`ship_from.address`	string	No	Pickup street address
`ship_from.city`	string	No	Pickup city (defaults to quote origin)
`ship_from.state`	string	No	Pickup state
`ship_from.zip`	string	No	Pickup ZIP
`ship_from.phone`	string	No	Pickup phone
`ship_from.email`	string	No	Pickup email
`ship_to`	object	No	Same fields as `ship_from`
`bill_to`	object	No	Billing details (company, contact, address, type)
`bill_to.type`	string	No	`prepaid`, `collect`, or `third_party`
`freight.description`	string	No	Commodity description
`freight.handling_unit_type`	string	No	e.g. "Pallet"
`freight.weight`	number	No	Weight in lbs
`freight.freight_class`	string	No	NMFC class
`references`	array	No	Up to 3 reference objects `{ name, value }`
`special_instructions`	string	No	Special handling instructions
`ship_date`	string	No	Requested ship date (ISO 8601)

Example

curl -X POST https://api.freightcake.com/api/v1/shipments \
  -H "Authorization: Bearer fk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": 1,
    "ship_from": {
      "company": "Acme Corp",
      "contact": "Jane Doe",
      "address": "123 W Adams St",
      "city": "Chicago", "state": "IL", "zip": "60601"
    },
    "ship_to": {
      "company": "Southeast Warehouse",
      "contact": "Bob Wilson",
      "address": "789 Peachtree St",
      "city": "Atlanta", "state": "GA", "zip": "30301"
    },
    "references": [{ "name": "PO Number", "value": "PO-2025-001" }]
  }'

Response

{
  "object": "shipment",
  "id": 1,
  "status": "draft",
  "pro_number": null,
  "carrier": { "name": "Sandbox Freight Co" },
  "quote": { "id": 1, "net_charge_cents": 35000 },
  "ship_from": { "company": "Acme Corp", ... },
  "ship_to": { "company": "Southeast Warehouse", ... },
  "created_at": "2025-07-01T00:00:00.000Z"
}

List Shipments

GET /v1/shipments

Query Parameters

Param	Type	Description
`limit`	number	Max results (1-100, default 25)
`starting_after`	string	Cursor for forward pagination
`status`	string	Filter by status: `draft`, `created`, `booked`, `in_transit`, `delivered`, `voided`

Retrieve Shipment

GET /v1/shipments/:id

Update Shipment

PATCH /v1/shipments/:id

Only draft shipments can be updated. Accepts the same fields as create (except quote_id).

Cancel Shipment

POST /v1/shipments/:id/cancel

Cancels a shipment. Draft shipments are voided immediately. Booked shipments enter a "Void Requested" flow.

Cancellable Statuses

draft → Voided immediately
created, booked, scheduled → Void requested (requires carrier approval)

Shipment Tracking

GET /v1/shipments/:id/tracking

Returns tracking status for a specific shipment.

Bill of Lading

GET /v1/shipments/:id/bol — BOL as JSON

GET /v1/shipments/:id/bol/pdf — BOL as PDF download

On this page