--- title: "Create or Update Loads" method: POST path: "/loads" tags: ["loads"] --- # Create or Update Loads `POST /loads` ## Request - Base URL: `https://demo-developer.convoy.com/broker` - URL: `https://demo-developer.convoy.com/broker/loads` - Auth: HTTP bearer Queues up the creation or updates of existing loads. Inputs are validated against the API schema immediately and errors are returned in the response, but specific load data is validated asynchronously (such as whether addresses can be geocoded). Subsequent calls to this API using the same `externalId` are used to update the already created load. This API should be used to ensure that loads are kept in sync with any other source of truth your brokerage maintains such as your TMS. Load updates should be pushed to this API as soon as changes are made in other systems to avoid duplicate actions across systems, such as loads matched with multiple carriers. All loads should be synced to ensure loads are not orphaned if not updated in subsequent syncs. Load should be synced for up to three days after completion or cancellation. This API does not currently support other modes of transportation than full truckload freight. Ocean, Intermodal, Air, LTL, Tanker, etc. should be not be synced with this API. Use Cases: - Make a load available in the Convoy marketplace by creating a load marked with a `postingStatus: AVAILABLE` - Update a load available in the Convoy marketplace by sending the updated information along with the `externalId` of the load - Cancel a load in the Convoy marketplace, such as when they are canceled in your TMS, by sending the load along with a `postingStatus: CANCELED` - Mark a load as already covered by a carrier outside not matched by Convoy by sending `postingStatus: COVERED` along with the externalId of the load. ## Headers - `X-Convoy-API-Version` string, required ## Request body - LoadRequest - `loads` Load[], required: A load to create or update. All fields are displayed to carriers unless otherwise specified. - union - AvailableLoad - `externalId` string, required: Unique ID for the load, recommended to match a unique identifier in the caller's external system. This identifier will only be displayed to the carrier after booking. - `referenceIds` ReferenceId[]: Reference numbers for the load (Shipment ID #, Bill of Lading #, PO #). For stop specific reference numbers use reference ids on stops. This will not be displayed to the carrier prior to booking the load. - `value` string, required: The value of the reference number (e.g 123456). - `label` string: The type of reference number (e.g. Bill of Lading #, Shipment #) - `notes` string: Load specific notes or instructions. This is show to carriers prior to booking the load. Do not specify pickup, delivery or appointment numbers in this field. - `postingRates` PostingRates - `maxBuyRateCents` integer: The maximum rate at which a carrier can match on the load. This value is required to post a load to the Convoy Platform marketplace (when postingStatus: AVAILABLE). This rate will not be displayed to the carrier, and is used to derive the bookNowRateCents. - `autoAcceptRateCents` integer: Bids below this rate will be automatically accepted. (Bids above this rate may also be accepted by the pricing model.) This rate will not be displayed to the carrier. If not provided, this value is calculated by the pricing model. If provided, this value must be lower than or equal to maxBuyRateCents. - `shipper` Shipper - `externalId` string: Unique ID for the shipper, recommended to match a unique identifier in the caller’s external system. This will not be displayed to the carrier. This should not change for the lifetime of the load. - `companyName` string: The name of the shipper - `assignedCarrier` union: Details of the assigned carrier to the load. Used to verify if carrier was matched on the Convoy marketplace or externally. - CarrierMcOnly - `mcNumber` string, required: The FMCSA Operating Authority (MC number) of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `dotNumber` string: The USDOT number of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `companyName` string: The name of the assigned carrier company. - CarrierDotOnly - `mcNumber` string: The FMCSA Operating Authority (MC number) of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `dotNumber` string, required: The USDOT number of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `companyName` string: The name of the assigned carrier company. - `metadata` Metadata: This parameter can be used to attach arbitrary key-value data to these loads. Metadata is useful for storing additional structured information, such as other internal identifiers, shipper or facility info. A maximum of 50 key-value pairs can be specified per load. All values must be a string less than 512 characters long. This will not be displayed to the carrier. - PendingLoad - `externalId` string, required: Unique ID for the load, recommended to match a unique identifier in the caller's external system. This identifier will only be displayed to the carrier after booking. - `referenceIds` ReferenceId[]: Reference numbers for the load (Shipment ID #, Bill of Lading #, PO #). For stop specific reference numbers use reference ids on stops. This will not be displayed to the carrier prior to booking the load. - `value` string, required: The value of the reference number (e.g 123456). - `label` string: The type of reference number (e.g. Bill of Lading #, Shipment #) - `notes` string: Load specific notes or instructions. This is show to carriers prior to booking the load. Do not specify pickup, delivery or appointment numbers in this field. - `postingRates` PostingRates - `maxBuyRateCents` integer: The maximum rate at which a carrier can match on the load. This value is required to post a load to the Convoy Platform marketplace (when postingStatus: AVAILABLE). This rate will not be displayed to the carrier, and is used to derive the bookNowRateCents. - `autoAcceptRateCents` integer: Bids below this rate will be automatically accepted. (Bids above this rate may also be accepted by the pricing model.) This rate will not be displayed to the carrier. If not provided, this value is calculated by the pricing model. If provided, this value must be lower than or equal to maxBuyRateCents. - `shipper` Shipper - `externalId` string: Unique ID for the shipper, recommended to match a unique identifier in the caller’s external system. This will not be displayed to the carrier. This should not change for the lifetime of the load. - `companyName` string: The name of the shipper - `assignedCarrier` union: Details of the assigned carrier to the load. Used to verify if carrier was matched on the Convoy marketplace or externally. - CarrierMcOnly - `mcNumber` string, required: The FMCSA Operating Authority (MC number) of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `dotNumber` string: The USDOT number of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `companyName` string: The name of the assigned carrier company. - CarrierDotOnly - `mcNumber` string: The FMCSA Operating Authority (MC number) of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `dotNumber` string, required: The USDOT number of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `companyName` string: The name of the assigned carrier company. - `metadata` Metadata: This parameter can be used to attach arbitrary key-value data to these loads. Metadata is useful for storing additional structured information, such as other internal identifiers, shipper or facility info. A maximum of 50 key-value pairs can be specified per load. All values must be a string less than 512 characters long. This will not be displayed to the carrier. - CoveredLoad - `externalId` string, required: Unique ID for the load, recommended to match a unique identifier in the caller's external system. This identifier will only be displayed to the carrier after booking. - `referenceIds` ReferenceId[]: Reference numbers for the load (Shipment ID #, Bill of Lading #, PO #). For stop specific reference numbers use reference ids on stops. This will not be displayed to the carrier prior to booking the load. - `value` string, required: The value of the reference number (e.g 123456). - `label` string: The type of reference number (e.g. Bill of Lading #, Shipment #) - `notes` string: Load specific notes or instructions. This is show to carriers prior to booking the load. Do not specify pickup, delivery or appointment numbers in this field. - `postingRates` PostingRates - `maxBuyRateCents` integer: The maximum rate at which a carrier can match on the load. This value is required to post a load to the Convoy Platform marketplace (when postingStatus: AVAILABLE). This rate will not be displayed to the carrier, and is used to derive the bookNowRateCents. - `autoAcceptRateCents` integer: Bids below this rate will be automatically accepted. (Bids above this rate may also be accepted by the pricing model.) This rate will not be displayed to the carrier. If not provided, this value is calculated by the pricing model. If provided, this value must be lower than or equal to maxBuyRateCents. - `shipper` Shipper - `externalId` string: Unique ID for the shipper, recommended to match a unique identifier in the caller’s external system. This will not be displayed to the carrier. This should not change for the lifetime of the load. - `companyName` string: The name of the shipper - `assignedCarrier` union: Details of the assigned carrier to the load. Used to verify if carrier was matched on the Convoy marketplace or externally. - CarrierMcOnly - `mcNumber` string, required: The FMCSA Operating Authority (MC number) of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `dotNumber` string: The USDOT number of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `companyName` string: The name of the assigned carrier company. - CarrierDotOnly - `mcNumber` string: The FMCSA Operating Authority (MC number) of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `dotNumber` string, required: The USDOT number of the carrier. Either MC Number of DOT Number is required for all postingStatus `COVERED` loads or unassignments. - `companyName` string: The name of the assigned carrier company. - `metadata` Metadata: This parameter can be used to attach arbitrary key-value data to these loads. Metadata is useful for storing additional structured information, such as other internal identifiers, shipper or facility info. A maximum of 50 key-value pairs can be specified per load. All values must be a string less than 512 characters long. This will not be displayed to the carrier. - CanceledLoad - `postingStatus` 'CANCELED', required - `externalId` string, required: Unique ID for the load, recommended to match a unique identifier in the caller's external system. This identifier will only be displayed to the carrier after booking. - `cancelReason` 'CARRIER_RATE_ISSUE' | 'NO_CALL_NO_SHOW' | 'SHIPMENT_ISSUE' | 'BROKER_MATCHED_INTERNALLY' | 'CARRIER_ISSUE_GENERAL' | 'CARRIER_PERFORMANCE_OR_BEHAVIOR' | 'CARRIER_DOES_NOT_WANT_LOAD' | 'CARRIER_UNRESPONSIVE_TO_FOLLOWUP' | 'CARRIER_QUALIFICATION' | 'BROKER_ISSUE' | 'SEVERE_WEATHER_OR_UNFORESEEN_EVENT' | 'NO_REASON_PROVIDED': The reason the load is either unassigned or canceled | Status | Description | | ---------------------------------- |-------------| | CARRIER_RATE_ISSUE | The carrier has an issue with the rate. | | NO_CALL_NO_SHOW | The carrier did not call or show up for the load. | | SHIPMENT_ISSUE | There was a general issue with the shipment. | | BROKER_MATCHED_INTERNALLY | The broker matched the load internally. | | CARRIER_ISSUE_GENERAL | There was a general issue with the carrier. | | CARRIER_PERFORMANCE_OR_BEHAVIOR | The carrier's performance or behavior was an issue. | | CARRIER_DOES_NOT_WANT_LOAD | The carrier does not want the load. | | CARRIER_UNRESPONSIVE_TO_FOLLOWUP | The carrier was unresponsive to followup. | | CARRIER_QUALIFICATION | The carrier's qualifications were not sufficient for the load. | | BROKER_ISSUE | There was a general issue with the broker. | | SEVERE_WEATHER_OR_UNFORESEEN_EVENT | Severe weather or unforeseen event occurred. | | NO_REASON_PROVIDED | No reason was provided. | - `cancelMessage` string: A message from the broker about why they canceled the load. - `brokerSelectedReason` string: The exact wording of what the broker selected in the TMS when canceling the load. ## Response `202` All or some loads were accepted for creation or updating. Each load is validated independently, so a 202 may include both accepted loads and loads rejected with per-load errors. Always inspect the `errors` field on each load rather than relying on the status code alone. - LoadResponse - `hasErrors` boolean: True when at least one load in the batch was rejected with per-load errors. Equivalent to `summary.rejected > 0`. Lets clients detect partial failure without scanning every load's `errors`. - `summary` LoadResponseSummary: Aggregate counts for a Create or Update Loads batch. - `accepted` integer, required: Number of loads accepted (no per-load errors). - `rejected` integer, required: Number of loads rejected with per-load errors. - `loads` object[] - `loadSyncId` string: The identifier for the resulting LoadSync. The [**load.sync.processed** event](./Webhooks/EventTypes.md) event will be emitted with this identifier when the synchronization process is complete. - `externalId` string, required: The externalId of the load sent in the request. - `errors` Error[]: If specified, an error occurred on a specific load, otherwise the creation or update was successful. Updates may be partially applied (valid fields still updated). For a list of errors see [Create or Update Loads Errors](./LoadSync/Errors.md) - `errorCode` string: For some errors that could be handled programmatically, a short string indicating the error code reported. Validation errors of the request have a `.openapi.validation` suffix (e.g. `required.openapi.validation` for required fields) - `message` string: A human-readable message providing more details about the error. - `path` string: The location of the error. Validation errors within the body of the request are prefixed with `.body.` (e.g. `.body.loads`) ## Other responses - `400`: Invalid request. No loads were created or updated. - `default`: Unexpected error --- [API](https://skmtc.dev/convoy/apis/brokers.md) - [All operations](https://skmtc.dev/convoy/apis/brokers/llms.txt) - [OpenAPI document](https://skmtc.dev/convoy/apis/brokers/revisions/a43e2868b355?raw)