{"templateId":"markdown","versions":[{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/freight/freight-quote-book","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/docs/freight/freight-quote-book","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/freight/freight-quote-book","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml","oas-apis/@shipengine/openapi.yaml":"oas-apis/@shipengine/openapi.yaml"},"props":{"metadata":{"markdoc":{"tagList":["openapi-code-sample","replay-openapi","admonition"]},"type":"markdown"},"seo":{"title":"Quote & Book Freight","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"quote--book-freight","__idx":0},"children":["Quote & Book Freight"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Booking LTL freight is always a two-step process: request quotes, then book one of the offers you get back. This page covers both steps, along with the provider account lookup they both depend on. For the concepts behind handling units, freight class, accessorials, and hazmat, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/shipengine/docs/freight/freight-overview"},"children":["Freight (LTL)"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-freight-provider-accounts","__idx":1},"children":["List Freight Provider Accounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["GET /v1/freight/provider_accounts"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Freight is quoted and booked through a freight provider account connected to your account, and every request on these endpoints names the account it goes through. Start here to find the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["freight_provider_account_id"]}," to use."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/@shipengine/openapi.yaml","operationId":"list_freight_provider_accounts","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"freight_provider_accounts\": [\n    {\n      \"freight_provider_account_id\": \"se-4821\",\n      \"freight_provider_name\": \"UNISHIPPERS\",\n      \"nickname\": \"Unishippers - Midwest\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only active connections are returned, so an account with no freight provider connected — or one whose connection has been disabled — gets an empty array. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["freight_provider_name"]}," is the provider's code, the same value that comes back on quotes, shipments, and tracking. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nickname"]}," is whatever the connection was named when it was set up, and is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when it has no name."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-freight-quotes","__idx":2},"children":["Get Freight Quotes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/freight/quotes"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Describe the freight and receive offers from the carriers available through your freight provider. Each offer is individually bookable."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/@shipengine/openapi.yaml","operationId":"get_freight_quotes","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also try this request in the browser:"]},{"$$mdtype":"Tag","name":"ReplayOpenApi","attributes":{"descriptionFile":"oas-apis/@shipengine/openapi.yaml","operationId":"get_freight_quotes","parameters":{},"options":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"quoting-inline","__idx":3},"children":["Quoting Inline"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the origin, destination, and handling units directly. Freight carriers need a contact name, company name, and phone number at both ends of the shipment, so those fields are required on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_from"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_to"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"freight_provider_account_id\": \"se-4821\",\n  \"shipment_date\": \"2026-04-17T00:00:00Z\",\n  \"ship_from\": {\n    \"name\": \"Marcus Bell\",\n    \"company_name\": \"Northgate Distribution\",\n    \"address_line1\": \"4200 Industrial Pkwy\",\n    \"address_line2\": \"Dock 12\",\n    \"city_locality\": \"Grand Rapids\",\n    \"state_province\": \"MI\",\n    \"postal_code\": \"49512\",\n    \"country_code\": \"US\",\n    \"phone\": \"+1 616 555 0142\",\n    \"location_type\": \"commercial\"\n  },\n  \"ship_to\": {\n    \"name\": \"Dana Reyes\",\n    \"company_name\": \"Reyes Home Furnishings\",\n    \"address_line1\": \"915 Commerce St\",\n    \"city_locality\": \"Dallas\",\n    \"state_province\": \"TX\",\n    \"postal_code\": \"75202\",\n    \"country_code\": \"US\",\n    \"phone\": \"+1 214 555 0198\",\n    \"location_type\": \"commercial\"\n  },\n  \"handling_units\": [\n    {\n      \"type\": \"pallet\",\n      \"quantity\": 2,\n      \"length\": 48,\n      \"width\": 40,\n      \"height\": 52,\n      \"stackable\": false,\n      \"commodities\": [\n        {\n          \"description\": \"Assembled oak dining chairs\",\n          \"quantity\": 24,\n          \"weight\": 310,\n          \"freight_class\": \"125\",\n          \"packaging_type\": \"carton\"\n        }\n      ]\n    }\n  ],\n  \"accessorials\": {\n    \"liftgate_delivery\": true,\n    \"notify_before_delivery\": true\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"quoting-an-existing-shipment","__idx":4},"children":["Quoting an Existing Shipment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," instead of addresses. The origin is read from the shipment's ship-from warehouse and the destination from the order's ship-to address."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"freight_provider_account_id\": \"se-4821\",\n  \"shipment_id\": \"se-28529731\",\n  \"handling_units\": [\n    {\n      \"type\": \"pallet\",\n      \"quantity\": 2,\n      \"length\": 48,\n      \"width\": 40,\n      \"height\": 52,\n      \"commodities\": [\n        { \"quantity\": 24, \"weight\": 310, \"freight_class\": \"125\" }\n      ]\n    }\n  ],\n  \"accessorials\": { \"liftgate_delivery\": true }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sending ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_from"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_to"]}," alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," is rejected. The shipment must have a ship-from warehouse and a destination address, otherwise the request returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["handling_units"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accessorials"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insurance"]}," you send here are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["saved as the shipment's freight configuration"]},". Quote the same shipment again with only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," and the saved configuration is reused:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"freight_provider_account_id\": \"se-4821\",\n  \"shipment_id\": \"se-28529731\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is what makes re-quoting cheap — adjust one thing, or nothing at all, and ask again."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reading-the-offers","__idx":5},"children":["Reading the Offers"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"quotes\": [\n    {\n      \"freight_provider_account_id\": \"se-4821\",\n      \"freight_provider_name\": \"UNISHIPPERS\",\n      \"quote_request_id\": \"7f1c9a52-3d84-4f0e-9b3a-2c6d5e4f8a10\",\n      \"offer_id\": \"0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68\",\n      \"carrier_name\": \"FedEx Freight Economy\",\n      \"carrier_scac\": \"FXFE\",\n      \"service_name\": \"Standard LTL\",\n      \"service_type\": \"Direct\",\n      \"total_charges\": 842.37,\n      \"transit_days\": 3,\n      \"estimated_delivery_date\": \"2026-04-22T00:00:00Z\",\n      \"is_guaranteed\": false,\n      \"origin_terminal_code\": \"GRR\",\n      \"destination_terminal_code\": \"DFW\",\n      \"quote_expiration_date\": \"2026-04-16T23:59:59Z\",\n      \"max_liability_new\": 25,\n      \"max_liability_used\": 10\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Four fields are what you carry into the booking request:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Why it matters"},"children":["Why it matters"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quote_request_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifies the quote request that produced the offers. The same value appears on every offer in the response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offer_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifies the specific offer you are booking."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_scac"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Standard Carrier Alpha Code of the carrier that would move the freight."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quote_expiration_date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the offer stops being bookable."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rest of the offer is there to help you choose. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_type"]}," tells you whether the origin terminal serves the lane itself (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Direct"]},") or hands the freight to another carrier (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Interline"]},") — interline moves involve an extra transfer. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_guaranteed"]}," distinguishes a guaranteed transit time from an estimate, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max_liability_new"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max_liability_used"]}," show the carrier's liability cap per pound, which is usually the argument for adding ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/shipengine/docs/freight/freight-overview#insurance"},"children":["insurance"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An empty or absent ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quotes"]}," array means no carrier available through that connection can serve the lane as described."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"book-a-freight-shipment","__idx":6},"children":["Book a Freight Shipment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/freight/shipments"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Book one of the offers. This dispatches the shipment with the carrier and generates the Bill of Lading."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/@shipengine/openapi.yaml","operationId":"book_freight_shipment","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also try this request in the browser:"]},{"$$mdtype":"Tag","name":"ReplayOpenApi","attributes":{"descriptionFile":"oas-apis/@shipengine/openapi.yaml","operationId":"book_freight_shipment","parameters":{},"options":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"booking-an-existing-shipment","__idx":7},"children":["Booking an Existing Shipment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the quote was linked to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]},", book with that same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]},". The origin, destination, and handling units all come from the shipment and its saved freight configuration, so ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_from"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_to"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["handling_units"]}," must be omitted."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"freight_provider_account_id\": \"se-4821\",\n  \"shipment_id\": \"se-28529731\",\n  \"quote_request_id\": \"7f1c9a52-3d84-4f0e-9b3a-2c6d5e4f8a10\",\n  \"offer_id\": \"0f2b41d8-6a17-4c9e-8f52-b71d3e9c4a68\",\n  \"carrier_scac\": \"FXFE\",\n  \"quote_expiration_date\": \"2026-04-16T23:59:59Z\",\n  \"pickup_details\": {\n    \"pickup_date\": \"2026-04-17T00:00:00Z\",\n    \"ready_time\": \"09:00\",\n    \"close_time\": \"16:30\",\n    \"is_self_scheduled\": false,\n    \"location_type\": \"commercial\"\n  },\n  \"references\": [\n    { \"type\": \"purchase_order\", \"value\": \"PO-84213\" }\n  ],\n  \"pickup_instructions\": \"Check in with the guard at gate 3 before backing into dock 12.\",\n  \"delivery_instructions\": \"Delivery appointments accepted between 08:00 and 11:00 only.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The shipment must already have a freight quote. Booking a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," with no saved freight configuration returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}," asking you to quote first, and a shipment whose freight plan was cancelled cannot be booked at all."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"booking-inline","__idx":8},"children":["Booking Inline"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," and provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_from"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_to"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["handling_units"]}," — the same objects you sent when quoting. A shipment record is created for the booking and marked as shipped."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pickup-details","__idx":9},"children":["Pickup Details"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pickup_details"]}," is required in both modes. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_time"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["close_time"]}," are 24-hour ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HH:mm"]}," values local to the origin, and they define the window a driver can arrive in."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the window realistic. A one-hour window is likely to be missed, and a missed pickup usually means the freight moves a day later. Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_self_scheduled"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," if you arrange the pickup with the carrier yourself; ShipStation API then does not request one on your behalf."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"references-and-instructions","__idx":10},"children":["References and Instructions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}," are printed on the Bill of Lading and are how your consignee and your own AP team recognize the shipment. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," is a free-form label such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase_order"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sales_order"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_1"]},". Which reference types a carrier can actually print varies by carrier, and so does the length a carrier keeps — the API does not length-check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]},", but freight providers commonly truncate references to around 35 characters, so keep them short."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The three instruction fields reach different people: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pickup_instructions"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery_instructions"]}," go to the drivers at each end, while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["handling_instructions"]}," travels with the freight."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-booking-response","__idx":11},"children":["The Booking Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"freight_shipment_id\": \"se-98765432\",\n  \"freight_provider_account_id\": \"se-4821\",\n  \"freight_provider_name\": \"UNISHIPPERS\",\n  \"status\": \"booked\",\n  \"product_transaction_id\": \"7f1c9a52-3d84-4f0e-9b3a-2c6d5e4f8a10\",\n  \"pickup_transaction_id\": \"3ac81f60-92b7-4de1-8f04-5b9a7c2e6d13\",\n  \"bol_number\": \"BOL-20260417-4821\",\n  \"pro_number\": null,\n  \"confirmation_number\": \"FXFE-PU-884215\",\n  \"documents\": [\n    { \"document_id\": null, \"type\": \"BILL_OF_LADING\", \"url\": null },\n    { \"document_id\": null, \"type\": \"PALLET_LABEL\", \"url\": null }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["freight_shipment_id"]}," — it is how you retrieve, track, and cancel the shipment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bol_number"]}," identifies the shipment on its paperwork and can be tracked immediately. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pro_number"]}," is the carrier's own tracking number and is often assigned only after pickup, so it is usually ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," here. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmation_number"]}," is the pickup confirmation from the carrier. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product_transaction_id"]}," is the provider's own identifier for the booked shipment — it is the same value you sent as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quote_request_id"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documents"]}," array tells you ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["what"]}," was generated, not where to get it: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document_id"]}," are always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," in the booking response. To download the documents, call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/shipengine/docs/freight/freight-manage#list-freight-shipment-documents"},"children":["List freight shipment documents"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Document type casing"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The booking response reports document types in the freight provider's own format, in uppercase (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BILL_OF_LADING"]},"). The document and shipment retrieval endpoints report them in lowercase (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bill_of_lading"]},") and include download URLs. Compare document types case-insensitively."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"expired-quotes","__idx":12},"children":["Expired Quotes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["LTL offers are short-lived — usually the same day. Booking an offer whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quote_expiration_date"]}," has passed returns:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"request_id\": \"4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a\",\n  \"errors\": [\n    {\n      \"error_source\": \"shipengine\",\n      \"error_type\": \"system\",\n      \"error_code\": \"unspecified\",\n      \"message\": \"The quote has expired. Please request a new quote.\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the shape ShipStation API uses for every pre-flight rejection on these endpoints — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_type"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unspecified"]},", and the specifics are in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},". The other rejections that arrive this way are a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," with no freight configuration, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," whose freight plan was cancelled, and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," missing its ship-from warehouse or destination address. Match on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," only for logging, never for control flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no way to extend an offer. Request fresh quotes and book from those. If your workflow involves human approval between quoting and booking, re-quote at the moment of approval rather than booking a stored offer."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"errors","__idx":13},"children":["Errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validation failed, the freight provider connection is not active, the quote expired, the linked shipment has no freight configuration or a cancelled one, or the provider rejected the request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]}," does not identify a shipment on your account."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every rejection falls into one of four shapes. Branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}," together with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_source"]},", never on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"error_source / error_type / error_code"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_source"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_type"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it means"},"children":["What it means"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipengine"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business_rules"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field_value_required"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unspecified"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request failed field validation, either because a required field was missing (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["handling_units is required and must contain at least one item"]},") or because a value broke a rule — an unrecognized ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["location_type"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["freight_class"]}," outside the accepted list, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready_time"]}," that is not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HH:mm"]},", a dimension that is not greater than zero, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_from"]}," sent alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment_id"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["field_name"]}," names the offending field, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," states the rule. Handle both codes: they are the same class of client-side mistake."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipengine"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unspecified"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request is well-formed but cannot proceed: the quote expired, the linked shipment has no freight configuration, its freight plan was cancelled, or it is missing its ship-from warehouse or destination address. The specifics are only in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business_rules"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unspecified"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The freight provider or carrier refused the request. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," carries the provider's own wording behind a fixed prefix."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provider and carrier rejections — a lane the carrier does not serve, a freight class it will not accept, an inactive provider connection — all come back as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," responses in this shape:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"request_id\": \"4b8e2f4c-1f6f-4b1a-9c4a-8f5e6d7c8b9a\",\n  \"errors\": [\n    {\n      \"error_source\": \"carrier\",\n      \"error_type\": \"business_rules\",\n      \"error_code\": \"unspecified\",\n      \"carrier_id\": \"se-4821\",\n      \"carrier_code\": \"unknown\",\n      \"carrier_name\": \"unknown\",\n      \"message\": \"A shipping carrier error occurred: No rates available for the requested lane.\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," is the provider's own wording behind the fixed prefix ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["A shipping carrier error occurred: "]},". That wording is the most specific information available, so log it — but strip the prefix before showing it to a user."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"The carrier fields do not mean what they look like"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On freight errors, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]}," is your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["freight_provider_account_id"]},", not a carrier ID you can use anywhere else. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_name"]}," are always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown"]},", because a freight offer does not map to a parcel carrier record. Ignore all three; use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_scac"]}," from the offer to identify the carrier."]}]}]},"headings":[{"value":"Quote & Book Freight","id":"quote--book-freight","depth":1},{"value":"List Freight Provider Accounts","id":"list-freight-provider-accounts","depth":2},{"value":"Get Freight Quotes","id":"get-freight-quotes","depth":2},{"value":"Quoting Inline","id":"quoting-inline","depth":3},{"value":"Quoting an Existing Shipment","id":"quoting-an-existing-shipment","depth":3},{"value":"Reading the Offers","id":"reading-the-offers","depth":3},{"value":"Book a Freight Shipment","id":"book-a-freight-shipment","depth":2},{"value":"Booking an Existing Shipment","id":"booking-an-existing-shipment","depth":3},{"value":"Booking Inline","id":"booking-inline","depth":3},{"value":"Pickup Details","id":"pickup-details","depth":3},{"value":"References and Instructions","id":"references-and-instructions","depth":3},{"value":"The Booking Response","id":"the-booking-response","depth":3},{"value":"Expired Quotes","id":"expired-quotes","depth":2},{"value":"Errors","id":"errors","depth":2}],"frontmatter":{"seo":{"title":"Quote & Book Freight"}},"lastModified":"2026-08-14T20:29:54.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/freight/freight-quote-book","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}