Build freight workflows without leaving your system.

Carrier clarity. One theme: where a carrier or a document cannot do what you asked, the API now says which carrier, why, and what to do — instead of a generic code to loop on. Every change is additive; nothing you already send behaves differently.

• PROs we issue are PROs we accept. The validator now takes every format OTT itself returns, including short Dot-Line PROs (e.g. 86820) and 10-digit Ward PROs, and it strips a leading carrier label (TForce:) or #. Previously our own booking could hand back a PRO our own tracking refused with 422. The 422 detail now lists the accepted shapes.
• A manual booking says so. When OTT dispatch completes the booking by hand (Ward, OTT lane, forwarding, or a carrier whose auto-book is off), the response carries status: "BOOKING_REQUESTED", pro: null, bookingMode: "manual" and a plain warnings[] line telling you the PRO will appear on GET /quotes/{id}. status is documented as BOOKED | BOOKING_REQUESTED, and sandbox is always present.
• POD says which carrier it cannot fetch. A POD request for a carrier we do not serve from the API now returns 501 document_not_supported naming the carrier, the supported carriers and the number to call. It used to return a 404 "No pod on file", which read as "the carrier has none". A 404 now means "not available yet" and says whether the shipment has been delivered. POD content types now cover TIFF/PNG/JPEG scans.
• A lane nobody serves is not a retry loop. POST /quotes answers 422 unprocessable with a carriers[] array (carrier + short reason: no_service, rejected, needs_assistance, timeout, unavailable, unknown) when every carrier declined, and 503 + Retry-After only when a carrier could not be reached. Before, both were a 503 with no explanation.
• Forwarding is labelled correctly. A freight-forwarding (WorldTrak) shipment is no longer reported as TForce: bookings, BOLs and tracking rows name WorldTrak, and its tracking answers 501 not_implemented with the dispatch number instead of a 404 from another carrier's system. Tracking responses now always include carrier.
• Test keys are safer. Re-creating a test key can no longer re-enable a sandbox OTT disabled, and two accounts with the same company name can no longer share one sandbox. Behaviour for a healthy sandbox is unchanged.

Test keys. Create an ott_test_ key yourself under API Access. It uses the same base URL and the same scopes as your live key. Quotes and rates are real; booking is simulated (no carrier is contacted), and tracking and BOL/POD return labelled sample data for the test PRO the booking returns. No request or response shapes changed for live keys; simulated bookings add "sandbox": true.

Item dimensions are now required on POST /quotes. Carriers re-rate every shipment on measured size and weight and bill the difference (extreme-length, cube, reweigh). A class-only quote can't price those adjustments, so we now rate on real dimensions to keep your quotes accurate and avoid surprise re-rates.

• Required now — a quote missing any line item's length, width, or height is refused with 422 validation_failed. Send each commodity with dimsIn: { length, width, height } in inches.
• Canonical shape — use the commodities[] array (each line with dimsIn, weightLbs,pieces, freightClass). The legacy flat weightLbs/freightClass body can't carry dimensions and is no longer accepted for rating.
• Commodity description field — each commodity line now accepts an optional plain-text description (e.g. "machine parts"). Prints on the BOL; does not affect the rate.

Documentation accuracy update — no request or response shapes changed. Brings the published reference in line with current live behavior.

• Extended dimension ceiling — the per-side limit is now 336" (28 ft), not 96". Loads up to the ceiling are rated online with per-carrier extreme-length handling; only a side over 336" is refused with 422.
• Carrier selection with carrierOptionId — POST /quotes returns a carrierOptionId on every option; pass it unchanged to POST /quotes/{id}/book to book that exact priced option. A stale or unknown id returns 409.
• Quote-expiry booking gate clarified — booking an unbooked quote past its validity window (default 3 days) is refused with 409 conflict. (Previously documented as advisory-only or a 422; the live behavior is a 409.)

Invoice document retrieval on GET /shipments/{pro}/documents/{type}. Backward-compatible — bol and pod are unchanged.

• Invoice PDF — request type=invoice to download your OnTime Trucking invoice as application/pdf once the shipment is booked (before booking it returns 404). It is the same invoice shown in the OTT portal, and contains customer-facing information only — never carrier cost or margin. No new scope: it uses the existing shipment:read.
• Bill of Lading as PDF — add ?format=pdf to type=bol to receive the BOL as application/pdf. Backward-compatible: omit it and bol still returns HTML as before.

Volume / spot rating for large and multi-pallet loads on POST /quotes. Backward-compatible — standard LTL requests are unchanged.

• Volume / spot quoting — send ratingMode: "VOLUME" with linearFeet (8–28) to rate a large load off linear feet instead of freight class. Omit both for standard class-based LTL.
• Automatic cubic-capacity spot rating — OTT computes each load's cube and density and auto-runs a spot quote per carrier when it trips that carrier's cubic-capacity rule (TForce Item 575: 750+ cu ft and under 6 lb/cu ft), with no pallet-count threshold. Volume lanes that need a manual spot quote return a clear 422 pointing to OTT dispatch (not a retryable error).
• Safer input compatibility — per-commodity dims and dimensions are accepted as aliases for dimsIn; common accessorial labels are normalized to OTT codes; malformed or conflicting values return structured field errors.

Backward-compatible additions and stricter request validation. The endpoint path is unchanged (/api/v1) — the path only changes for a breaking redesign.

• Multi-commodity quoting — send commodities[] (max 30 lines) on POST /quotes; each line rates with its own freight class and the top-level weightLbs/pieces/freightClass become optional aggregates. When present, commodities[] is the rating source of truth.
• Per-commodity NMFC — each line accepts an nmfc item number (also available as a single-commodity nmfc). Prints on the BOL; does not affect price.
• commodities[].dimsIn validation — dimensions live only inside a per-line dimsIn object ({ length, width, height } in inches, all three required together). A side over 336" (28 ft), or dimensions sent at the wrong level, is now rejected with 422 naming the offending field — before any carrier call.
• Booking notes and customerReference on POST /quotes/{id}/book — customerReference (your PO, echoed on shipment reads) and notes (special-handling text printed on the OTT BOL).

• Initial public v1: POST /quotes, GET /quotes/{id}, POST /quotes/{id}/book, GET /shipments/{pro}, and GET /shipments/{pro}/tracking.
• Bearer API-key auth with account-inherited scopes, RFC 7807 errors with a stable code, per-client rate limits, and X-Request-Id on every response.