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.freight.create({
  quote_id: 1042,

  ship_from: {
    company: 'Acme Corp',
    contact: 'Jane Doe',
    address: '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',
    address: '456 S Main St',
    city: 'Los Angeles',
    state: 'CA',
    zip: '90001',
    phone: '213-555-0200',
  },

  freight: {
    description: 'Pallet of widgets',
    handling_unit_type: 'Pallet',
    handling_quantity: 1,
    weight: 500,
    freight_class: '70',
  },
  references: [{ name: 'PO Number', value: 'PO-12345' }],
  ship_date: '2026-07-15',
  special_instructions: 'Dock 4, ring bell',
})

console.log(`Shipment ${shipment.id} booked with ${shipment.carrier?.name}`)
console.log(`PRO number: ${shipment.pro_number ?? 'pending'}`)

What you get back

{
  "object": "freight",
  "id": 9001,
  "status": "booked",
  "pro_number": "12345-678",
  "carrier": {
    "name": "Sandbox Freight Co",
    "scac": "SBFC"
  },
  "quote": {
    "id": 1042,
    "quote_number": "SBX-1042",
    "net_charge_cents": 30200,
    "service_level": "Standard LTL"
  },
  "ship_date": "2026-07-15",
  "pdf_url": null,
  "created_at": "2026-07-10T18:32:18.512Z"
}

Download the BOL separately after booking:

const bolResponse = await fc.freight.getBolPdf(String(shipment.id))
const bolPdf = Buffer.from(await bolResponse.arrayBuffer())

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.freight.cancel(String(shipment.id))

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

Ship dates must be valid for the selected quote. Re-quote when the quote has expired or the shipment date changes materially.
Address completeness matters. Validate saved addresses with fc.addresses.validate() before booking when user-entered data may be incomplete.
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 lifecycle events