{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/shippers/visibility/ftl/sidebars.yaml"},"props":{"codeGuideFiles":[],"dynamicMarkdocComponents":[],"metadata":{"type":"markdown"},"seo":{"title":"Truckload Unified Arrangements [Beta] - project44 Developer Portal","description":"Draft API documentation and user guide for the Truckload Unified Arrangements beta feature."},"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"truckload-unified-arrangements-beta"},"children":["Truckload Unified Arrangements [Beta]"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Beta: available on request."]}," Truckload Unified Arrangements is a beta feature; documentation and behavior are subject to change before general availability. Contact your project44 account team to enable it for your tenant."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview"},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full Truckload (FTL) is the one visibility mode that has historically created shipments through its own endpoint, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v4/tl/shipments"]},", rather than the unified shipment API used by ocean, rail, and the other modes. Truckload Unified Arrangements brings FTL onto the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v4/shipments/tracking"]}," endpoint and the same structured ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["plan"]},", so you can create truckload shipments with an explicit declaration of the carrier and the route."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every truckload shipment you create through this API is built from three parts:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transportation mode"]}," identifies the shipment as truckload. You declare it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.expectedTransportationModes"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"TRUCKLOAD\"]"]},". This is what activates truckload tracking and validation; truckload does not use scope tags."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A carrier arrangement"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]},") declares the trucking company that moves the load and supplies the identifiers the platform needs to activate tracking, including the equipment (phone, vehicle, or device) used to locate the truck."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A route"]}," declares the planned stops, their appointment windows, and their locations. Truckload requires at least an origin and a destination, so the route is a first-class part of the plan rather than something the platform discovers."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.expectedTransportationModes"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.arrangements"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]}," extend the existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan"]}," object in the unified shipment schema alongside top-level fields such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifiers"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page is for developers and logistics professionals who integrate with the project44 API to track truckload shipments. If you're migrating an existing FTL integration, each ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#business-scenarios"},"children":["business scenario"]}," pairs the legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v4/tl/shipments"]}," payload with its unified-arrangements equivalent."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin"},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before using the Truckload Unified Arrangements feature, make sure you have the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An active project44 API client ID and secret, used to generate bearer tokens for authentication"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The correct permissions enabled on your tenant for the features you intend to use; contact your project44 account team if you're unsure"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Familiarity with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v4/shipments/tracking"]}," endpoint and the unified shipment schema"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The information required to track a truckload shipment: a carrier identifier, at least two stops with appointment windows and locations, and, in most cases, an equipment identifier"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Access to the appropriate regional endpoint for your environment:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["North America:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://na12.api.project44.com/api/v4/shipments/tracking"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Europe:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://eu12.api.project44.com/api/v4/shipments/tracking"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sandbox:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://na12.api.sandbox.p-44.com/api/v4/shipments/tracking"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-plan"},"children":["The plan"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every truckload shipment you create includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan"]}," object at the top level of the unified shipment structure. For truckload you configure three fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expectedTransportationModes"]},": set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"TRUCKLOAD\"]"]}," to declare the mode. This drives truckload validation and sets the mode on the route segments the platform builds."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arrangements"]},": an array of objects. For truckload, the arrangement that matters is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement, which identifies the trucking company and provides the references needed to track the load."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["route"]},": the planned stops, in order, with their appointment windows and locations."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following shows how these fields fit within the broader shipment structure:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identifiers\": [\n    { \"type\": \"BILL_OF_LADING\", \"value\": \"BOL-XPOL-2026-0455\" },\n    { \"type\": \"CARRIER_SCAC\", \"value\": \"XPOL\" }\n  ],\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"XPOL\",\n            \"billOfLadingNumber\": \"BOL-XPOL-2026-0455\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" },\n                \"priority\": 1\n              }\n            ]\n          }\n        }\n      }\n    ],\n    \"route\": {\n      \"stops\": [\n        {\n          \"sequenceNumber\": 1,\n          \"type\": \"PICKUP\",\n          \"location\": {\n            \"name\": \"Lakeside Manufacturing\",\n            \"address\": {\n              \"addressLines\": [\"2200 W Canal St\"],\n              \"city\": \"Milwaukee\",\n              \"state\": \"WI\",\n              \"postalCode\": \"53233\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-03T08:00:00-05:00\",\n            \"endDateTime\": \"2026-08-03T12:00:00-05:00\"\n          }\n        },\n        {\n          \"sequenceNumber\": 2,\n          \"type\": \"DELIVERY\",\n          \"location\": {\n            \"name\": \"Riverside Distribution Center\",\n            \"address\": {\n              \"addressLines\": [\"1400 S Kostner Ave\"],\n              \"city\": \"Chicago\",\n              \"state\": \"IL\",\n              \"postalCode\": \"60623\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-03T15:00:00-05:00\",\n            \"endDateTime\": \"2026-08-03T18:00:00-05:00\"\n          }\n        }\n      ]\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example dates are illustrative."]}," The payloads on this page use fixed 2026 appointment dates for readability. Because truckload requires at least one appointment window in the future, replace the example dates with upcoming dates before you submit a request."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transportation-mode"},"children":["Transportation mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.expectedTransportationModes"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"TRUCKLOAD\"]"]},". This is how the platform recognizes the shipment as truckload: it runs the truckload validation rules and sets the mode on the route segments generated from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]},". Truckload does not use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.scope"]},"; scope tags are specific to other modes and are ignored for truckload."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"arrangements"},"children":["Arrangements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arrangements"]}," field is an array of objects. Each arrangement declares one party involved in the shipment. For truckload, the relevant arrangement is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]},", which identifies the trucking company that moves the load. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#the-carrier-arrangement"},"children":["The carrier arrangement"]}," for the field-level reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"route"},"children":["Route"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["route"]}," field declares the shipment's planned path. It contains a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stops"]}," array; each stop carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequenceNumber"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["location"]},", and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arrivalWindow"]}," (and optionally a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["departureWindow"]},"). The platform orders stops by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequenceNumber"]},", mints a stop ID for each, and builds the route segments between consecutive stops. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#the-planned-route"},"children":["The planned route"]}," for the field-level reference and the validation rules truckload enforces."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Declare the route on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]},". Do not also send a top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeInfo"]}," object: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]}," is the customer-declared path, and the persisted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeInfo"]}," is derived from it. Supplying both is rejected with a validation error."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-carrier-arrangement"},"children":["The carrier arrangement"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement represents the trucking company that moves the load. A truckload shipment must resolve to at least one carrier identifier, so every shipment includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scac"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each arrangement supports two top-level identifier fields used to match it on subsequent updates:"]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (UUID)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Platform-generated UUID assigned when the arrangement is first created. Returned in the response. Provide this on subsequent requests to update the same arrangement."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer-provided string. Tenant-scoped and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["immutable after creation"]},": it cannot be changed, cleared, or added once the arrangement has been stored. Use this as a stable handle when you want to match arrangements by your own identifier rather than the platform-generated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#arrangement-behavior-on-post-and-put"},"children":["Arrangement behavior on POST and PUT"]}," for how ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," are used during matching."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The carrier details live under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details.truckloadCarrier"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"fields"},"children":["Fields"]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scac"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Standard carrier alpha code. At least one of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scac"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]}," is required so the platform can resolve the carrier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["US DOT number. Satisfies the carrier-identifier requirement on its own."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Motor carrier (MC) number. Satisfies the carrier-identifier requirement on its own."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nmcCarrierId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["National motor carrier ID used by some connections."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["masterCarrierId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Master carrier ID used to group carrier entities."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billOfLadingNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bill of lading number for the shipment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order number for the shipment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["equipmentIdentifiers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tracking methods for the load. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#equipment-identifiers"},"children":["Equipment identifiers"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stops"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Carrier-specific stops for this leg. For a single-carrier truckload, declare the route once on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]}," instead."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The carrier fields are promoted to shipment-level identifiers when the arrangement is stored: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scac"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CARRIER_SCAC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CARRIER_US_DOT_NUMBER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CARRIER_MC_NUMBER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billOfLadingNumber"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BILL_OF_LADING"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderNumber"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ORDER"]},". If you also list any of these at the top level of the request, the values must match the arrangement; a conflict is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ARRANGEMENT_IDENTIFIER_MISMATCH"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"equipment-identifiers"},"children":["Equipment identifiers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Equipment identifiers tell the platform how to track the vehicle carrying the load. Each entry pairs an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier"]}," (a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]},") with an optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["priority"]},". Lower priority numbers are tried first, so you can list a preferred tracking method and one or more fallbacks."]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier.type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tracking method. See the accepted values below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier.value"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The value for the tracking method (phone number, vehicle ID, plate, or device ID)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["priority"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order in which tracking methods are attempted. Lower is tried first."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accepted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier.type"]}," values:"]},{"$$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":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MOBILE_PHONE_NUMBER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Driver's mobile phone number, tracked through the carrier's mobile app or an SMS-based method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VEHICLE_ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Vehicle or truck ID reported by the carrier's ELD / telematics connection."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LICENSE_PLATE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tractor or trailer license plate."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SENSITECH_DEVICE_ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sensitech monitoring device ID (reefer / condition monitoring)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EMERSON_DEVICE_ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Emerson monitoring device ID (reefer / condition monitoring)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TIVE_DEVICE_ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tive tracker device ID."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Equipment identifiers are also promoted to shipment-level identifiers of the matching type."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-planned-route"},"children":["The planned route"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Truckload shipments must declare their route at creation time. The route lives on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route.stops"]}," as an ordered list of stops. The platform sorts stops by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequenceNumber"]},", assigns each a stop ID, preserves the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," you supply, and generates the route segments between consecutive stops using the mode from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expectedTransportationModes"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"stop-fields"},"children":["Stop fields"]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequenceNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Position of the stop in the route, starting at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," for the origin. Stops are ordered by this value."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stop type. See the accepted values below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your own identifier for the stop. Preserved on the derived stop and used to bind incoming events to the right stop."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["location"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Where the stop is. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#stop-location-fields"},"children":["Stop location fields"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arrivalWindow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Appointment window for arrival. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startDateTime"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDateTime"]},", both offset date-times. An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDateTime"]}," is required."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["departureWindow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Appointment window for departure, if tracked separately."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accepted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," values for truckload:"]},{"$$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":"Value"},"children":["Value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PICKUP"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Where the vehicle is loaded with the shipment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ORIGIN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Where the truck is filled by the shipper with the goods to be transported."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSFER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An intermediate transfer stop."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELIVERY"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Where the shipment is delivered."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DESTINATION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Where the shipment is finally delivered."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"stop-location-fields"},"children":["Stop location fields"]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable name for the location."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Postal address. See below. Provide an address or coordinates."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.addressLines"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array of strings"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Street address lines."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.city"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["City. Required when the location is given by address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["State or province. Required when the location is given by address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.postalCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Postal / ZIP code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address.country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 3166-1 alpha-2 country code. Required when the location is given by address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coordinates.latitude"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Latitude. Provide coordinates or an address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coordinates.longitude"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Longitude. Provide coordinates or an address."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeZone"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["IANA time zone for the stop (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["America/Chicago"]},")."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"route-validation-rules"},"children":["Route validation rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Truckload applies the following rules at create time. Each failure returns a machine-readable error code in the response."]},{"$$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":"Rule"},"children":["Rule"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error code"},"children":["Error code"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["At least two stops are required."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_MISSING_SHIPMENT_STOP"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every stop must have an arrival appointment window."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_MISSING_APPOINTMENT_WINDOW"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Each arrival window must include an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDateTime"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_APPOINTMENT_WINDOW_NO_END_DATE"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["At least one appointment must be in the future."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_APPOINTMENT_WINDOW_IN_THE_PAST"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every stop must carry enough location detail: valid coordinates, or an address with at least city, state, and country."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_INSUFFICIENT_LOCATION_INFORMATION"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A carrier identifier (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scac"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]},") must be resolvable."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_MISSING_CARRIER_IDENTIFIER"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The time zone that used to sit inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["appointmentWindow.localTimeZoneIdentifier"]}," in the legacy API now lives on the stop's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["location.timeZone"]},". Appointment windows carry offset date-times directly."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements"},"children":["Requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a valid truckload shipment through this API:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.expectedTransportationModes"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"TRUCKLOAD\"]"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement with a resolvable carrier identifier (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scac"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provide at least two stops on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route.stops"]},", each with a location and an arrival appointment window with an end date. At least one appointment must be in the future."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add an equipment identifier so tracking can start immediately. Depending on the carrier connection type it may not be required, but sending one is the reliable default."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"business-scenarios"},"children":["Business scenarios"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Truckload tracking spans a range of setups: loads booked directly with an asset carrier, loads tracked by different equipment methods, and multi-stop routes. Previously, every setup used the same payload shape on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v4/tl/shipments"]},": a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrierIdentifier"]},", a flat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipmentIdentifiers"]}," list, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipmentStops"]}," array, and a top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["equipmentIdentifiers"]}," list. That model spread the carrier, its shipment references, and its equipment across separate top-level fields with no clear ownership."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]}," consolidate those signals and move truckload onto the unified endpoint. Each of the following scenarios pairs the legacy payload with its unified-arrangements equivalent to support a one-by-one migration of an existing integration."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Same validation, earlier."]}," The unified payloads enforce the same truckload rules the legacy endpoint applies (two stops, appointment windows, a resolvable carrier), but they run at create time against a single structured request, so you get actionable errors before tracking is attempted."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"scenario-1-ftl-booked-directly-with-an-asset-carrier"},"children":["Scenario 1: FTL booked directly with an asset carrier"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business case:"]}," A shipper tenders a full truckload directly to an asset carrier and tracks the driver by mobile phone."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transportation mode:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key arrangement:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," (SCAC + bill of lading + mobile phone)"]}]},{"$$mdtype":"Tag","name":"table","attributes":{"width":"100%","style":{"height":"1px","tableLayout":"fixed"}},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["Before this API"]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["With unified arrangements"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"carrierIdentifier\": { \"type\": \"SCAC\", \"value\": \"XPOL\" },\n  \"shipmentIdentifiers\": [{ \"type\": \"BILL_OF_LADING\", \"value\": \"BOL-XPOL-2026-0455\" }],\n  \"shipmentStops\": [\n    {\n      \"stopNumber\": 1,\n      \"appointmentWindow\": {\n        \"startDateTime\": \"2026-08-03T08:00:00\",\n        \"endDateTime\": \"2026-08-03T12:00:00\",\n        \"localTimeZoneIdentifier\": \"America/Chicago\"\n      },\n      \"location\": {\n        \"address\": {\n          \"addressLines\": [\"2200 W Canal St\"],\n          \"city\": \"Milwaukee\",\n          \"state\": \"WI\",\n          \"postalCode\": \"53233\",\n          \"country\": \"US\"\n        }\n      }\n    },\n    {\n      \"stopNumber\": 2,\n      \"appointmentWindow\": {\n        \"startDateTime\": \"2026-08-03T15:00:00\",\n        \"endDateTime\": \"2026-08-03T18:00:00\",\n        \"localTimeZoneIdentifier\": \"America/Chicago\"\n      },\n      \"location\": {\n        \"address\": {\n          \"addressLines\": [\"1400 S Kostner Ave\"],\n          \"city\": \"Chicago\",\n          \"state\": \"IL\",\n          \"postalCode\": \"60623\",\n          \"country\": \"US\"\n        }\n      }\n    }\n  ],\n  \"equipmentIdentifiers\": [{ \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" }]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"XPOL\",\n            \"billOfLadingNumber\": \"BOL-XPOL-2026-0455\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" },\n                \"priority\": 1\n              }\n            ]\n          }\n        }\n      }\n    ],\n    \"route\": {\n      \"stops\": [\n        {\n          \"sequenceNumber\": 1,\n          \"type\": \"PICKUP\",\n          \"location\": {\n            \"address\": {\n              \"addressLines\": [\"2200 W Canal St\"],\n              \"city\": \"Milwaukee\",\n              \"state\": \"WI\",\n              \"postalCode\": \"53233\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-03T08:00:00-05:00\",\n            \"endDateTime\": \"2026-08-03T12:00:00-05:00\"\n          }\n        },\n        {\n          \"sequenceNumber\": 2,\n          \"type\": \"DELIVERY\",\n          \"location\": {\n            \"address\": {\n              \"addressLines\": [\"1400 S Kostner Ave\"],\n              \"city\": \"Chicago\",\n              \"state\": \"IL\",\n              \"postalCode\": \"60623\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-03T15:00:00-05:00\",\n            \"endDateTime\": \"2026-08-03T18:00:00-05:00\"\n          }\n        }\n      ]\n    }\n  }\n}\n","lang":"json"},"children":[]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What changed:"]}," The carrier, its bill of lading, and the driver's phone number all sit inside one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement instead of three separate top-level fields. The stop time zone moves from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["appointmentWindow.localTimeZoneIdentifier"]}," onto ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["location.timeZone"]},", and appointment windows carry offset date-times."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"scenario-2-ftl-tracked-by-eld-vehicle-id"},"children":["Scenario 2: FTL tracked by ELD vehicle ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business case:"]}," The carrier tracks through an ELD / telematics connection rather than a driver's phone, so the load is anchored on a vehicle ID."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transportation mode:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key arrangement:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VEHICLE_ID"]}," equipment identifier"]}]},{"$$mdtype":"Tag","name":"table","attributes":{"width":"100%","style":{"height":"1px","tableLayout":"fixed"}},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["Before this API"]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["With unified arrangements"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsonc","header":{"controls":{"copy":{}}},"source":"{\n  \"carrierIdentifier\": { \"type\": \"SCAC\", \"value\": \"KNXT\" },\n  \"shipmentIdentifiers\": [{ \"type\": \"ORDER\", \"value\": \"PO-88213\" }],\n  \"shipmentStops\": [\n    /* origin and destination stops */\n  ],\n  \"equipmentIdentifiers\": [{ \"type\": \"VEHICLE_ID\", \"value\": \"TRK-4471\" }]\n}\n","lang":"jsonc"},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsonc","header":{"controls":{"copy":{}}},"source":"{\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"KNXT\",\n            \"orderNumber\": \"PO-88213\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"VEHICLE_ID\", \"value\": \"TRK-4471\" },\n                \"priority\": 1\n              }\n            ]\n          }\n        }\n      }\n    ],\n    \"route\": {\n      \"stops\": [\n        /* origin and destination stops */\n      ]\n    }\n  }\n}\n","lang":"jsonc"},"children":[]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What changed:"]}," The vehicle ID is scoped to the carrier arrangement that owns it, and the order number is declared explicitly (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderNumber"]},") rather than inferred from a flat identifier list."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"scenario-3-ftl-with-a-carrier-identified-by-dot-or-mc-number"},"children":["Scenario 3: FTL with a carrier identified by DOT or MC number"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business case:"]}," The carrier does not have a SCAC on file, or the integration keys off the DOT / MC number instead."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transportation mode:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key arrangement:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]}," (and optionally ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]},")"]}]},{"$$mdtype":"Tag","name":"table","attributes":{"width":"100%","style":{"height":"1px","tableLayout":"fixed"}},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["Before this API"]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["With unified arrangements"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsonc","header":{"controls":{"copy":{}}},"source":"{\n  \"carrierIdentifier\": { \"type\": \"DOT_NUMBER\", \"value\": \"2131234\" },\n  \"shipmentIdentifiers\": [{ \"type\": \"BILL_OF_LADING\", \"value\": \"BOL-2026-0512\" }],\n  \"shipmentStops\": [\n    /* origin and destination stops */\n  ],\n  \"equipmentIdentifiers\": [{ \"type\": \"LICENSE_PLATE\", \"value\": \"IL-AB12345\" }]\n}\n","lang":"jsonc"},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsonc","header":{"controls":{"copy":{}}},"source":"{\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"dotNumber\": \"2131234\",\n            \"mcNumber\": \"MC-654321\",\n            \"billOfLadingNumber\": \"BOL-2026-0512\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"LICENSE_PLATE\", \"value\": \"IL-AB12345\" },\n                \"priority\": 1\n              }\n            ]\n          }\n        }\n      }\n    ],\n    \"route\": {\n      \"stops\": [\n        /* origin and destination stops */\n      ]\n    }\n  }\n}\n","lang":"jsonc"},"children":[]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What changed:"]}," The carrier can be resolved from any of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scac"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]},", each in its own field, instead of a single typed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrierIdentifier"]},". Supply more than one when you have them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"scenario-4-multi-stop-ftl"},"children":["Scenario 4: Multi-stop FTL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business case:"]}," A single truckload picks up at one origin and delivers to two consignees, with an intermediate stop in between."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transportation mode:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key arrangement:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," + a three-stop route"]}]},{"$$mdtype":"Tag","name":"table","attributes":{"width":"100%","style":{"height":"1px","tableLayout":"fixed"}},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["Before this API"]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["With unified arrangements"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"carrierIdentifier\": { \"type\": \"SCAC\", \"value\": \"XPOL\" },\n  \"shipmentIdentifiers\": [{ \"type\": \"BILL_OF_LADING\", \"value\": \"BOL-XPOL-2026-0460\" }],\n  \"shipmentStops\": [\n    {\n      \"stopNumber\": 1,\n      \"appointmentWindow\": {\n        \"startDateTime\": \"2026-08-05T07:00:00\",\n        \"endDateTime\": \"2026-08-05T10:00:00\",\n        \"localTimeZoneIdentifier\": \"America/Chicago\"\n      },\n      \"location\": {\n        \"address\": {\n          \"addressLines\": [\"2200 W Canal St\"],\n          \"city\": \"Milwaukee\",\n          \"state\": \"WI\",\n          \"postalCode\": \"53233\",\n          \"country\": \"US\"\n        }\n      }\n    },\n    {\n      \"stopNumber\": 2,\n      \"appointmentWindow\": {\n        \"startDateTime\": \"2026-08-05T13:00:00\",\n        \"endDateTime\": \"2026-08-05T15:00:00\",\n        \"localTimeZoneIdentifier\": \"America/Chicago\"\n      },\n      \"location\": {\n        \"address\": {\n          \"addressLines\": [\"500 S 27th St\"],\n          \"city\": \"Milwaukee\",\n          \"state\": \"WI\",\n          \"postalCode\": \"53215\",\n          \"country\": \"US\"\n        }\n      }\n    },\n    {\n      \"stopNumber\": 3,\n      \"appointmentWindow\": {\n        \"startDateTime\": \"2026-08-05T18:00:00\",\n        \"endDateTime\": \"2026-08-05T21:00:00\",\n        \"localTimeZoneIdentifier\": \"America/Chicago\"\n      },\n      \"location\": {\n        \"address\": {\n          \"addressLines\": [\"1400 S Kostner Ave\"],\n          \"city\": \"Chicago\",\n          \"state\": \"IL\",\n          \"postalCode\": \"60623\",\n          \"country\": \"US\"\n        }\n      }\n    }\n  ],\n  \"equipmentIdentifiers\": [{ \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" }]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"XPOL\",\n            \"billOfLadingNumber\": \"BOL-XPOL-2026-0460\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" },\n                \"priority\": 1\n              }\n            ]\n          }\n        }\n      }\n    ],\n    \"route\": {\n      \"stops\": [\n        {\n          \"sequenceNumber\": 1,\n          \"type\": \"PICKUP\",\n          \"referenceId\": \"PICKUP-MKE\",\n          \"location\": {\n            \"address\": {\n              \"addressLines\": [\"2200 W Canal St\"],\n              \"city\": \"Milwaukee\",\n              \"state\": \"WI\",\n              \"postalCode\": \"53233\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-05T07:00:00-05:00\",\n            \"endDateTime\": \"2026-08-05T10:00:00-05:00\"\n          }\n        },\n        {\n          \"sequenceNumber\": 2,\n          \"type\": \"DELIVERY\",\n          \"referenceId\": \"DROP-MKE-SOUTH\",\n          \"location\": {\n            \"address\": {\n              \"addressLines\": [\"500 S 27th St\"],\n              \"city\": \"Milwaukee\",\n              \"state\": \"WI\",\n              \"postalCode\": \"53215\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-05T13:00:00-05:00\",\n            \"endDateTime\": \"2026-08-05T15:00:00-05:00\"\n          }\n        },\n        {\n          \"sequenceNumber\": 3,\n          \"type\": \"DELIVERY\",\n          \"referenceId\": \"DROP-CHI\",\n          \"location\": {\n            \"address\": {\n              \"addressLines\": [\"1400 S Kostner Ave\"],\n              \"city\": \"Chicago\",\n              \"state\": \"IL\",\n              \"postalCode\": \"60623\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-05T18:00:00-05:00\",\n            \"endDateTime\": \"2026-08-05T21:00:00-05:00\"\n          }\n        }\n      ]\n    }\n  }\n}\n","lang":"json"},"children":[]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What changed:"]}," Stop order is declared by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequenceNumber"]},", and each stop carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," you control. The platform builds a route segment between each consecutive pair of stops, and inbound events that reference a stop by its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," bind to the right stop and segment automatically."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"scenario-5-ftl-with-prioritized-fallback-tracking"},"children":["Scenario 5: FTL with prioritized fallback tracking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business case:"]}," The carrier can be tracked by more than one method and the integration wants a preferred method with a fallback."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transportation mode:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Key arrangement:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," with multiple prioritized equipment identifiers"]}]},{"$$mdtype":"Tag","name":"table","attributes":{"width":"100%","style":{"height":"1px","tableLayout":"fixed"}},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["Before this API"]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%"},"children":["With unified arrangements"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{"style":{"height":"1px"}},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsonc","header":{"controls":{"copy":{}}},"source":"{\n  \"carrierIdentifier\": { \"type\": \"SCAC\", \"value\": \"XPOL\" },\n  \"shipmentIdentifiers\": [{ \"type\": \"BILL_OF_LADING\", \"value\": \"BOL-XPOL-2026-0491\" }],\n  \"shipmentStops\": [\n    /* origin and destination stops */\n  ],\n  \"equipmentIdentifiers\": [\n    { \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" },\n    { \"type\": \"VEHICLE_ID\", \"value\": \"TRK-4471\" }\n  ]\n}\n","lang":"jsonc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The two equipment identifiers were an unordered list; there was no way to say which to try first."]}]},{"$$mdtype":"Tag","name":"td","attributes":{"style":{"verticalAlign":"top","height":"100%"}},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsonc","header":{"controls":{"copy":{}}},"source":"{\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"XPOL\",\n            \"billOfLadingNumber\": \"BOL-XPOL-2026-0491\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" },\n                \"priority\": 1\n              },\n              {\n                \"identifier\": { \"type\": \"VEHICLE_ID\", \"value\": \"TRK-4471\" },\n                \"priority\": 2\n              }\n            ]\n          }\n        }\n      }\n    ],\n    \"route\": {\n      \"stops\": [\n        /* origin and destination stops */\n      ]\n    }\n  }\n}\n","lang":"jsonc"},"children":[]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What changed:"]}," The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["priority"]}," field makes the fallback order explicit. The platform tries the lowest priority number first (the mobile phone) and falls back to the next (the vehicle ID) when the preferred method can't be established."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"linking-shipments-via-shared-arrangements"},"children":["Linking shipments via shared arrangements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When several truckload shipments move under the same carrier booking, give each shipment's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement the same top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]},". The platform treats arrangements that share a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," as the same underlying entity, so the shared arrangement provides a navigable link across those shipments. Each shipment still tracks independently."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsonc","header":{"controls":{"copy":{}}},"source":"{\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"referenceId\": \"CARRIER-XPOL-BOOKING-77120\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"XPOL\",\n            \"billOfLadingNumber\": \"BOL-XPOL-2026-0455\"\n          }\n        }\n      }\n    ],\n    \"route\": {\n      \"stops\": [\n        /* origin and destination stops */\n      ]\n    }\n  }\n}\n","lang":"jsonc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because the two shipments' carrier arrangements share the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]},", the platform resolves them to one underlying entity. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#arrangement-behavior-on-post-and-put"},"children":["Arrangement behavior on POST and PUT"]}," for the full matching rules around ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoints"},"children":["Endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following endpoints are available for truckload shipment tracking through the unified API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"post-/shipments/tracking"},"children":["POST /shipments/tracking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creates a new shipment or appends data to an existing one. This operation is additive: it never removes existing arrangements. If you provide a shipment ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," that already exists, the operation merges the new data with the existing record."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Full path:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v4/shipments/tracking"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-headers"},"children":["Request headers"]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bearer token. Format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer <access-token>"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-body-parameters"},"children":["Request body parameters"]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["project44-assigned shipment UUID. Provide this to append data to an existing shipment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifiers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logistics identifiers associated with the shipment. Must not conflict with the carrier arrangement fields."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.expectedTransportationModes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array of strings"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"TRUCKLOAD\"]"]}," to identify the shipment as truckload."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.arrangements"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array of objects"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Declares the carrier. Include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#the-carrier-arrangement"},"children":["The carrier arrangement"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route.stops"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array of objects"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The planned stops, in order. At least two are required. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#the-planned-route"},"children":["The planned route"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["attributes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User-defined custom attributes to associate with the shipment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entitledAccessGroups"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Access groups entitled to visibility of this shipment."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not send a top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeInfo"]}," object alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]},"; the persisted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeInfo"]}," is derived from the plan."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-example"},"children":["Request example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identifiers\": [\n    { \"type\": \"BILL_OF_LADING\", \"value\": \"BOL-XPOL-2026-0455\" },\n    { \"type\": \"CARRIER_SCAC\", \"value\": \"XPOL\" }\n  ],\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"XPOL\",\n            \"billOfLadingNumber\": \"BOL-XPOL-2026-0455\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" },\n                \"priority\": 1\n              }\n            ]\n          }\n        }\n      }\n    ],\n    \"route\": {\n      \"stops\": [\n        {\n          \"sequenceNumber\": 1,\n          \"type\": \"PICKUP\",\n          \"location\": {\n            \"address\": {\n              \"addressLines\": [\"2200 W Canal St\"],\n              \"city\": \"Milwaukee\",\n              \"state\": \"WI\",\n              \"postalCode\": \"53233\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-03T08:00:00-05:00\",\n            \"endDateTime\": \"2026-08-03T12:00:00-05:00\"\n          }\n        },\n        {\n          \"sequenceNumber\": 2,\n          \"type\": \"DELIVERY\",\n          \"location\": {\n            \"address\": {\n              \"addressLines\": [\"1400 S Kostner Ave\"],\n              \"city\": \"Chicago\",\n              \"state\": \"IL\",\n              \"postalCode\": \"60623\",\n              \"country\": \"US\"\n            },\n            \"timeZone\": \"America/Chicago\"\n          },\n          \"arrivalWindow\": {\n            \"startDateTime\": \"2026-08-03T15:00:00-05:00\",\n            \"endDateTime\": \"2026-08-03T18:00:00-05:00\"\n          }\n        }\n      ]\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"response-fields"},"children":["Response fields"]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID of the created or updated shipment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifiers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logistics identifiers, including the ones promoted from the carrier arrangement."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The shipment plan, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expectedTransportationModes"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arrangements"]}," (each with an assigned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"). The planned route is returned as the derived ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeInfo"]}," object below, not on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeInfo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stops and route segments derived from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipmentShareLink"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Publicly accessible link to the shipment details page."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdDateTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (date-time)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp when the shipment was created. Read-only."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastModifiedDateTime"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (date-time)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp when the shipment was last modified. Read-only."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"response-example"},"children":["Response example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"3b6bff66-c74b-475c-a222-ce6a92413650\",\n  \"identifiers\": [\n    { \"type\": \"BILL_OF_LADING\", \"value\": \"BOL-XPOL-2026-0455\" },\n    { \"type\": \"CARRIER_SCAC\", \"value\": \"XPOL\" },\n    { \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" }\n  ],\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"id\": \"a1b2c3d4-5566-7788-99aa-bbccddeeff00\",\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"XPOL\",\n            \"billOfLadingNumber\": \"BOL-XPOL-2026-0455\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"MOBILE_PHONE_NUMBER\", \"value\": \"+13125550147\" },\n                \"priority\": 1\n              }\n            ]\n          }\n        }\n      }\n    ]\n  },\n  \"routeInfo\": {\n    \"stops\": [\n      { \"id\": \"c1000000-0000-4000-a000-000000000010\", \"type\": \"PICKUP\" },\n      { \"id\": \"c1000000-0000-4000-a000-000000000011\", \"type\": \"DELIVERY\" }\n    ],\n    \"routeSegments\": [\n      {\n        \"id\": \"d1000000-0000-4000-a000-000000000010\",\n        \"fromStopId\": \"c1000000-0000-4000-a000-000000000010\",\n        \"toStopId\": \"c1000000-0000-4000-a000-000000000011\",\n        \"transportationMode\": \"TRUCKLOAD\"\n      }\n    ]\n  },\n  \"shipmentShareLink\": \"https://movement.project44.com/share/abc123xyz\",\n  \"createdDateTime\": \"2026-07-23T09:15:00Z\",\n  \"lastModifiedDateTime\": \"2026-07-23T09:15:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"error-codes"},"children":["Error codes"]},{"$$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":"Description"},"children":["Description"]}]}]},{"$$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 response body includes a machine-readable error code and an actionable message. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#truckload-validation-errors"},"children":["Truckload validation errors"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication failed. Your bearer token is missing or invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your account doesn't have the required permission for this operation."]}]},{"$$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 shipment ID you provided doesn't exist."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An unexpected server error occurred. If this persists, contact project44 support."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"put-/shipments/tracking"},"children":["PUT /shipments/tracking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Updates an existing shipment. Unlike ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},", the request payload defines the complete arrangement set for the shipment: arrangements absent from the request are unlinked, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," on matched arrangements are fully replaced rather than merged. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#arrangement-behavior-on-post-and-put"},"children":["Arrangement behavior on POST and PUT"]}," for the precise rules."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Full path:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /api/v4/shipments/tracking"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-body-parameters-1"},"children":["Request body parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," request body uses the same schema as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},". You must provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," to identify the shipment you're replacing."]},{"$$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":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["project44-assigned shipment UUID of the shipment to replace."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.expectedTransportationModes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array of strings"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[\"TRUCKLOAD\"]"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.arrangements"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array of objects"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The arrangement set for the shipment. Omit the field or send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," for a no-op; send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[]"]}," to unlink every arrangement; send a non-empty list to snapshot-replace (any arrangement not included is then unlinked). See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#arrangement-behavior-on-post-and-put"},"children":["Arrangement behavior on POST and PUT"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-example-1"},"children":["Request example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"3b6bff66-c74b-475c-a222-ce6a92413650\",\n  \"plan\": {\n    \"expectedTransportationModes\": [\"TRUCKLOAD\"],\n    \"arrangements\": [\n      {\n        \"id\": \"a1b2c3d4-5566-7788-99aa-bbccddeeff00\",\n        \"type\": \"TRUCKLOAD_CARRIER\",\n        \"details\": {\n          \"truckloadCarrier\": {\n            \"scac\": \"XPOL\",\n            \"billOfLadingNumber\": \"BOL-XPOL-2026-0455\",\n            \"equipmentIdentifiers\": [\n              {\n                \"identifier\": { \"type\": \"VEHICLE_ID\", \"value\": \"TRK-4471\" },\n                \"priority\": 1\n              }\n            ]\n          }\n        }\n      }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"error-codes-1"},"children":["Error codes"]},{"$$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":"Description"},"children":["Description"]}]}]},{"$$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 response body includes a machine-readable error code and an actionable message."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication failed. Your bearer token is missing or invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your account doesn't have the required permission for this operation."]}]},{"$$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 shipment ID you provided doesn't exist."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An unexpected server error occurred. If this persists, contact project44 support."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"arrangement-behavior-on-post-and-put"},"children":["Arrangement behavior on POST and PUT"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both methods match each request arrangement against stored arrangements by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," (see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#the-carrier-arrangement"},"children":["The carrier arrangement"]}," for how these are populated). The methods differ in what they write to a matched arrangement, and whether arrangements omitted from the payload are affected."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Arrangements are shared across shipments."]}," An arrangement is a tenant-scoped entity that can be linked to many shipments at the same time. The same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]},") always refers to the same underlying arrangement, regardless of which shipment is being updated. Updating an arrangement via any one shipment mutates the underlying entity, so the new state is visible on every other shipment the arrangement is linked to."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"post-append-and-link-with-a-partial-merge"},"children":["POST: append-and-link with a partial merge"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A matched arrangement is updated by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["partial merge"]},": only the fields present in the request are written. Fields absent from the request are left unchanged."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An arrangement with no match is created and linked to the shipment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Arrangements omitted from the payload are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["left untouched"]},". POST never unlinks."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"put-snapshot-replace-of-the-shipments-arrangement-set"},"children":["PUT: snapshot-replace of the shipment's arrangement set"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The shape of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.arrangements"]}," in the request determines behavior:"]},{"$$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":"plan.arrangements in the request"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.arrangements"]}," in the request"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Behavior"},"children":["Behavior"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["field absent or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No-op. Arrangements and their links are untouched."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["empty list ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every arrangement linked to this shipment is unlinked. The arrangements themselves are not deleted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["non-empty list ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[...]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Snapshot-replace (see the rules that follow)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a non-empty list:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A matched arrangement has its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["fully replaced"]}," by the request's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," (subject to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#immutability-rules-post-and-put"},"children":["immutability rules"]},"). Other top-level fields (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]},") cannot change."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An arrangement with no match is created and linked."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stored arrangements linked to the shipment but ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["absent from the request"]}," are unlinked. The arrangement entities are not deleted."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After a successful PUT with a non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.arrangements"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," on the shipment returns exactly the arrangements supplied in the request, in the same order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"immutability-rules-post-and-put"},"children":["Immutability rules (POST and PUT)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following are rejected with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Changing a stored arrangement's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," to a different non-null value."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Setting a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," on a stored arrangement whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," (it can only be set at creation)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Clearing a stored arrangement's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Two arrangements in the same payload sharing the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supplying both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," where they resolve to different stored arrangements (identity conflict)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supplying an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," that does not exist."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"idempotency"},"children":["Idempotency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both methods are idempotent at the operation level when each arrangement carries a stable identifier. Retries that produce no state change emit no operations. Arrangements supplied with neither ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," nor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," are treated as new on every call: include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenceId"]}," for retry-safe writes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"truckload-validation-errors"},"children":["Truckload validation errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Truckload requests are validated at create time. The following error codes are specific to truckload and returned with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," status."]},{"$$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 code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to fix"},"children":["How to fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_MISSING_CARRIER_IDENTIFIER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No carrier identifier could be resolved."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supply ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scac"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dotNumber"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcNumber"]}," on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_CARRIER"]}," arrangement, or a matching top-level carrier identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_MISSING_SHIPMENT_STOP"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fewer than two stops were provided."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provide at least an origin and a destination in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route.stops"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_MISSING_APPOINTMENT_WINDOW"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A stop has no arrival appointment window."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Add an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["arrivalWindow"]}," to every stop. The message names the stop number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_APPOINTMENT_WINDOW_NO_END_DATE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A stop's arrival window has no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDateTime"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Add an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endDateTime"]}," to every arrival window."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_APPOINTMENT_WINDOW_IN_THE_PAST"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No appointment window is in the future."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Make sure at least one stop's appointment window is upcoming."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUCKLOAD_INSUFFICIENT_LOCATION_INFORMATION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A stop lacks enough location detail."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provide valid coordinates, or an address with at least city, state, and country. The message names the stop number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ARRANGEMENT_IDENTIFIER_MISMATCH"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A carrier arrangement field conflicts with a top-level identifier of the same type."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Make the arrangement value and the top-level identifier match, or remove one of them."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PLAN_ROUTE_AND_ROUTE_INFO_BOTH_PROVIDED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request carried both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeInfo"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send the route on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan.route"]}," only; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["routeInfo"]}," is derived from it."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the shared error-response schema (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},") and the meaning of each field, see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/shippers/visibility/ftl/appendix#error-response-codes"},"children":["Appendix"]},"."]}]},"headings":[{"value":"Truckload Unified Arrangements [Beta]","id":"truckload-unified-arrangements-beta","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Before you begin","id":"before-you-begin","depth":2},{"value":"The plan","id":"the-plan","depth":2},{"value":"Transportation mode","id":"transportation-mode","depth":3},{"value":"Arrangements","id":"arrangements","depth":3},{"value":"Route","id":"route","depth":3},{"value":"The carrier arrangement","id":"the-carrier-arrangement","depth":2},{"value":"Fields","id":"fields","depth":4},{"value":"Equipment identifiers","id":"equipment-identifiers","depth":4},{"value":"The planned route","id":"the-planned-route","depth":2},{"value":"Stop fields","id":"stop-fields","depth":4},{"value":"Stop location fields","id":"stop-location-fields","depth":4},{"value":"Route validation rules","id":"route-validation-rules","depth":4},{"value":"Requirements","id":"requirements","depth":2},{"value":"Business scenarios","id":"business-scenarios","depth":2},{"value":"Scenario 1: FTL booked directly with an asset carrier","id":"scenario-1-ftl-booked-directly-with-an-asset-carrier","depth":3},{"value":"Scenario 2: FTL tracked by ELD vehicle ID","id":"scenario-2-ftl-tracked-by-eld-vehicle-id","depth":3},{"value":"Scenario 3: FTL with a carrier identified by DOT or MC number","id":"scenario-3-ftl-with-a-carrier-identified-by-dot-or-mc-number","depth":3},{"value":"Scenario 4: Multi-stop FTL","id":"scenario-4-multi-stop-ftl","depth":3},{"value":"Scenario 5: FTL with prioritized fallback tracking","id":"scenario-5-ftl-with-prioritized-fallback-tracking","depth":3},{"value":"Linking shipments via shared arrangements","id":"linking-shipments-via-shared-arrangements","depth":3},{"value":"Endpoints","id":"endpoints","depth":2},{"value":"POST /shipments/tracking","id":"post-/shipments/tracking","depth":3},{"value":"Request headers","id":"request-headers","depth":4},{"value":"Request body parameters","id":"request-body-parameters","depth":4},{"value":"Request example","id":"request-example","depth":4},{"value":"Response fields","id":"response-fields","depth":4},{"value":"Response example","id":"response-example","depth":4},{"value":"Error codes","id":"error-codes","depth":4},{"value":"PUT /shipments/tracking","id":"put-/shipments/tracking","depth":3},{"value":"Request body parameters","id":"request-body-parameters-1","depth":4},{"value":"Request example","id":"request-example-1","depth":4},{"value":"Error codes","id":"error-codes-1","depth":4},{"value":"Arrangement behavior on POST and PUT","id":"arrangement-behavior-on-post-and-put","depth":3},{"value":"POST: append-and-link with a partial merge","id":"post-append-and-link-with-a-partial-merge","depth":4},{"value":"PUT: snapshot-replace of the shipment's arrangement set","id":"put-snapshot-replace-of-the-shipments-arrangement-set","depth":4},{"value":"Immutability rules (POST and PUT)","id":"immutability-rules-post-and-put","depth":4},{"value":"Idempotency","id":"idempotency","depth":4},{"value":"Truckload validation errors","id":"truckload-validation-errors","depth":2}],"frontmatter":{"seo":{"title":"Truckload Unified Arrangements [Beta] - project44 Developer Portal","description":"Draft API documentation and user guide for the Truckload Unified Arrangements beta feature."}},"lastModified":"2026-08-03T11:48:22.000Z"},"slug":"/guides/shippers/visibility/ftl/truckload-unified-arrangements","userData":{"isAuthenticated":false,"teams":["anonymous"]}}