Create a shipment

Once you have a winning quote ID from the rate shop walkthrough, booking the shipment is a single call.

The full request

import { fc } from './freightcake'

const shipment = await fc.shipments.create({
  quote_id: 1042,

  ship_from: {
    company: 'Acme Corp',
    contact: 'Jane Doe',
    address1: '123 W Adams St',
    city: 'Chicago',
    state: 'IL',
    zip: '60601',
    phone: '312-555-0100',
    email: 'jane@acme.example',
  },

  ship_to: {
    company: 'West Coast Warehouse',
    contact: 'John Smith',
    address1: '456 S Main St',
    city: 'Los Angeles',
    state: 'CA',
    zip: '90001',
    phone: '213-555-0200',
  },

  pickup: {
    date: '2026-05-20', // ISO yyyy-mm-dd, future business day
    ready_time: '08:00',
    close_time: '17:00',
    instructions: 'Dock 4, ring bell',
  },

  reference_numbers: {
    customer_po: 'PO-12345',
    bol_number: 'BOL-2026-0042',
  },
})

console.log(`Shipment ${shipment.id} booked with ${shipment.carrier_name}`)
console.log(`Tracking: ${shipment.tracking_number}`)
console.log(`BOL PDF: ${shipment.documents.bol_url}`)

What you get back

{
  "object": "shipment",
  "id": 9001,
  "status": "scheduled",
  "carrier_name": "Sandbox Freight Co",
  "carrier_scac": "SBFC",
  "tracking_number": "SBFC0009001",
  "pro_number": "12345-678",
  "pickup": {
    "date": "2026-05-20",
    "confirmation_number": "PU-58291",
    "status": "scheduled"
  },
  "documents": {
    "bol_url": "https://api.freightcake.com/v1/shipments/9001/bol.pdf",
    "label_urls": [
      "https://api.freightcake.com/v1/shipments/9001/label-1.pdf"
    ]
  },
  "total_charge_cents": 30200,
  "expected_delivery_date": "2026-05-25",
  "created_at": "2026-05-19T14:32:18.512Z"
}

The BOL PDF is generated synchronously and the URL is signed with a 7-day expiry. Download and store it in your own storage if you need it longer.

Status lifecycle

A booked shipment moves through these states. Each transition fires a webhook.

Status	Meaning
`scheduled`	Booked with the carrier, awaiting pickup
`picked_up`	Carrier confirmed pickup; in-transit
`in_transit`	Moving between carrier terminals
`out_for_delivery`	On the delivery truck
`delivered`	Confirmed delivered with PoD
`exception`	Something went wrong — see Track a shipment
`cancelled`	Cancelled before pickup

Cancelling a shipment

Cancel before pickup with no fee:

await fc.shipments.cancel(shipment.id, {
  reason: 'customer_changed_mind',
})

After pickup, cancellation requires intercept-and-return, which is a paid service depending on the carrier. The API returns cancellation_not_allowed in that case — handle it as a customer-facing exception.

Common gotchas

Pickup dates must be a future business day. The API will reject past dates and weekends with invalid_pickup_date. Saturday pickup is available on certain lanes — set accessorials: ['saturday_pickup'] at quote time and confirm the carrier returned a quote that supports it.
Address completeness matters. Missing suite numbers cause delivery exceptions. The SDK validates against USPS / SmartyStreets at submit time if you set validate_addresses: true (recommended).
The BOL is the legal document. Once a shipment is picked_up, the BOL is signed and changes require a carrier amendment (slow, manual). Get the ship-from / ship-to right before booking.

Next steps

Track the shipment to surface status to your end users
Set up webhook endpoints for shipment.status_changed events