Getting Started

Overview

The FreightCake API lets you programmatically quote, book, track, and manage LTL freight shipments. It follows REST conventions with JSON request/response bodies, Stripe-style resource envelopes, and cursor-based pagination.

Base URL:

https://api.freightcake.com/api/v1

Quick Start

1. Get your API key

Create API keys from the FreightCake dashboard under Settings → API Keys. Create separate keys for the modes you need:

Test key (fk_test_...) — for isolated test data and configured test integrations
Live key (fk_live_...) — for production with real carrier rates

2. Get a freight quote

curl -X POST https://api.freightcake.com/api/v1/quotes \
  -H "Authorization: Bearer fk_test_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "city": "Chicago", "state": "IL", "zip": "60601" },
    "destination": { "city": "Los Angeles", "state": "CA", "zip": "90001" },
    "items": [{
      "weight": 500,
      "freight_class": "70",
      "length": 48, "width": 40, "height": 48
    }]
  }'

Response:

{
  "object": "list",
  "url": "/api/v1/quotes",
  "data": [
    {
      "object": "quote",
      "id": 42,
      "carrier_name": "Sandbox Freight Co",
      "service_level": "Standard LTL",
      "net_charge_cents": 17500,
      "delivery_estimate": "3-5 business days",
      "expires_at": "2026-07-07T00:00:00.000Z"
    }
  ],
  "has_more": false
}

3. Book the shipment

curl -X POST https://api.freightcake.com/api/v1/freight \
  -H "Authorization: Bearer fk_test_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": 42,
    "ship_from": {
      "company": "Acme Corp",
      "contact": "Jane Doe",
      "address": "123 W Adams St",
      "city": "Chicago", "state": "IL", "zip": "60601",
      "phone": "312-555-0100"
    },
    "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"
    }
  }'

4. Track the shipment

curl https://api.freightcake.com/api/v1/freight/1/tracking \
  -H "Authorization: Bearer fk_test_REPLACE_WITH_YOUR_KEY"

Want a deeper dive? The Walkthroughs section rebuilds each of the four steps above as full integration recipes — with TypeScript SDK examples, response shapes, common gotchas, and links to the underlying reference. Start with Rate shop an LTL shipment.

Core Concepts

Authentication

All API requests require a Bearer token. See Authentication for details.

Live vs. Test Mode

Every API request is either in live mode or test mode, determined by the API key prefix:

Key prefix	Mode	Description
`fk_live_`	Live	Real carrier rates and shipments
`fk_test_`	Test	Isolated test-mode data

Test and live data are completely isolated — test-mode keys can only see test-mode objects.

Response Format

All responses follow a consistent envelope:

{
  "object": "quote",
  "id": 42,
  "quote_number": "SBX-0042",
  "carrier_name": "Sandbox Freight Co",
  "net_charge_cents": 17500
}

List endpoints use cursor-based pagination:

{
  "object": "list",
  "url": "/api/v1/quotes",
  "data": [
    {
      "object": "quote",
      "id": 42
    }
  ],
  "has_more": true
}

Error Handling

Errors return a structured error object:

{
  "error": {
    "type": "invalid_request_error",
    "message": "At least one item is required",
    "param": "items",
    "doc_url": "https://docs.freightcake.com/docs/api-reference/quotes"
  }
}

HTTP Status	Error Type
400	`invalid_request_error`
401	`authentication_error`
404	`invalid_request_error`
409	`idempotency_error`
422	`invalid_request_error`
429	`rate_limit_error`
500	`api_error`

Idempotency

POST requests support an Idempotency-Key header to safely retry operations:

curl -X POST https://api.freightcake.com/api/v1/freight \
  -H "Authorization: Bearer fk_test_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shipment-42-attempt-1" \
  -d '{ "quote_id": 42 }'

The API caches the response for 24 hours. Retries with the same key return the cached response.

On this page