Book a shipment

POST https://www.wearewarp.com/api/v1/book

Books a previously quoted shipment. The request body is one field: the quote_id from any quote response. Quoting is keyless on every mode. Booking is the single call that needs an API key and a card on file, and the key is self serve: sign up at /agents/account, no sales call.

Auth

Authorization: Bearer wak_live_... -- production key, books real freight
Authorization: Bearer wak_test_... -- sandbox key, books sandbox quotes only. Nothing ships, nothing is charged.

Request

quote_id -- the quote_id from any of the four quote endpoints: LTL, FTL, box truck, or van

curl example

curl -X POST https://www.wearewarp.com/api/v1/book \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wak_live_YOUR_KEY" \
  -d '{ "quote_id": "PRICING_..." }'

MCP tool call

{
  "tool": "book",
  "args": { "quote_id": "PRICING_..." }
}

CLI example

warp-agent book PRICING_...

Response

The confirmation carries the shipment_id you will track with, plus the live tracking dashboard URL.

{
  "booked": true,
  "shipment_id": "...",
  "shipment_number": "S-80215-2616",
  "order_id": "...",
  "order_number": "...",
  "tracking_number": "...",
  "lane_id": "ln_900_100",
  "tracking_dashboard": "https://customer.wearewarp.com"
}

Bookings are idempotent on quote_id

A quote_id is single use.

Retrying a book call with a quote_id your account already booked returns the original confirmation with idempotent_replay: true and never charges twice. A retry near the quote expiry edge also replays instead of failing, so a double submit from your agent is always safe.

{
  "booked": true,
  "idempotent_replay": true,
  "shipment_id": "...",
  "shipment_number": "S-80215-2616",
  "tracking_number": "...",
  "charged": 0,
  "already_charged_cents": 48500,
  "note": "This quote_id was already booked by your account; returning the original confirmation. No new charge was made."
}

How payment settles

A booking settles from your prepaid wallet balance first and charges your card only for any shortfall. Read GET /api/v1/balance before you book to know your runway.

Errors self describe the fix

PAYMENT_REQUIRED -- no card on file. The error includes a checkout_url: open it, add a card, then re-send the exact same book request.
QUOTE_NOT_FOUND -- the quote expired or does not exist. Re-run the quote (quotes are free) and book the fresh quote_id.
MISSING_DIMS -- an LTL quote needs length_in, width_in, height_in before it can book. Re-quote with dims.
SANDBOX_QUOTE_REQUIRED -- a wak_test_ key can only book a quote made with that same sandbox key.

Back to docs|Next: track this shipment