--- title: "Get quote for a multi-stops FTL shipment" method: POST path: "/freights/quote/multi-stops" tags: ["Multi-Stops"] --- # Get quote for a multi-stops FTL shipment `POST /freights/quote/multi-stops` ## Request - Base URL: `https://stg.wearewarp.com/api/v1` - URL: `https://stg.wearewarp.com/api/v1/freights/quote/multi-stops` - Auth: API key in header `apikey` Get a quote for a Full Truck Load (FTL) shipment with multiple stops (transit points). This endpoint allows you to get pricing for routes with intermediate pickup/delivery points between the origin and final destination. The pricing service calculates the total cost for the entire multi-stop route. **Requirements:** - At least 1 transit stop is required (otherwise use the standard `/freights/quote` endpoint) - Maximum 18 transit stops (20 total stops including pickup and delivery) - Only US ZIP codes are accepted at the moment (5-digit or ZIP+4). `country` "CA" passes the country check but Canadian postal codes fail the zipcode validation, so Canada cannot be quoted through multi-stops yet. **Rate limit:** this endpoint counts towards the FTL quoting rate limit of your API key (per UTC hour and per UTC day). Above the limit the API answers **429** `rate_limit_exceeded` with a `Retry-After` header. **Validation:** every validation error (including a missing required field) is returned as 400 `invalid_field_data` with the failing field in the message. **Request parameters** | Name | Type | Required/Optional | Description | |-------------------------|------------------------------|-------------------|-------------------------------------------------------------------------------------------------| | pickupDate | String | Required | The earliest pickup date in YYYY-MM-DD format, in the timezone of the pickup location. | | pickupInfo | Object | Required | Pickup stop details. | | pickupInfo.zipcode | String | Required | The postal code of the pickup location (US 5-digit or ZIP+4). | | pickupInfo.country | String | Optional | Country code (ISO 3166-1 alpha-2). Defaults to "US". See the US-only note above. | | deliveryInfo | Object | Required | Final delivery stop details. | | deliveryInfo.zipcode | String | Required | The postal code of the final delivery location (US 5-digit or ZIP+4). | | deliveryInfo.country | String | Optional | Country code (ISO 3166-1 alpha-2). Defaults to "US". See the US-only note above. | | transits | Array | Required | List of intermediate transit stops in route order. Min 1, max 18. | | transits[].zipcode | String | Required | The postal code of the transit stop (US 5-digit or ZIP+4). | | transits[].country | String | Optional | Country code (ISO 3166-1 alpha-2). Defaults to "US". See the US-only note above. | | listItems | Array<**Item**> | Required | The list of commodities being shipped (used for pricing the entire route). 1 to 100 items. | | pickupServices | Array<**ServiceOption**> | Optional | Pickup services required at the pickup location (max 20). | | deliveryServices | Array<**ServiceOption**> | Optional | Delivery services required at the delivery location (max 20). | | additionalServices | Array<**ServiceOption**> | Optional | Any additional services for the shipment (max 20). | | shipmentType | String | Optional | Only `FTL` is accepted (default: FTL); any other value is rejected with 400. | | vehicleType | Object | Optional | Vehicle type specification. | | vehicleType.code | String | Required when vehicleType is provided | Vehicle code (e.g. DRY_VAN_53, STRAIGHT_TRUCK_26, CARGO_VAN). |
**Item limits** (same **Item** schema as POST /freights/quote, with stricter bounds): | Field | Constraint | |-------------|---------------------------------------------------------------| | height | 0.1 - 85 | | length | 0.1 - 636 | | width | 0.1 - 102 | | quantity | integer, 1 - 9999 | | totalWeight | 0.01 - 80000 | | name | max 200 characters; notes max 500; freightClass/packaging max 50 |
**Response** | Name | Type | Description | |---------------------------|--------|----------------------------------------------------------------------------------------------| | quote_id | String | The unique ID for this quote (`WM` + ULID, 28 characters). Legacy `PRICING_MULTI_` ids are still accepted when booking. | | total_charge | Number | Total price for the entire multi-stop route (USD). | | transit_time | Number | Estimated transit time in seconds. | | transit_time_without_team | Number | Estimated transit time in seconds when the load is driven by a single driver instead of a team. | | rate_detail | Object | Detailed rate breakdown. | ## Request body - MultiStopsQuoteBody - `pickupDate` string, date, required: Pickup date in YYYY-MM-DD format - `pickupInfo` object, required - `zipcode` string, required: Postal code of the pickup location (US 5-digit or ZIP+4) - `country` 'US' | 'CA': Country code (ISO 3166-1 alpha-2). Defaults to US. Only US ZIP codes pass the zipcode validation at the moment, so CA cannot be quoted through multi-stops yet. - `deliveryInfo` object, required - `zipcode` string, required: Postal code of the final delivery location (US 5-digit or ZIP+4) - `country` 'US' | 'CA': Country code (ISO 3166-1 alpha-2). Defaults to US. Only US ZIP codes pass the zipcode validation at the moment, so CA cannot be quoted through multi-stops yet. - `transits` object[], required: Intermediate transit stops in route order (min 1, max 18) - `zipcode` string, required: Postal code of the transit stop (US 5-digit or ZIP+4) - `country` 'US' | 'CA': Country code (ISO 3166-1 alpha-2). Defaults to US. Only US ZIP codes pass the zipcode validation at the moment, so CA cannot be quoted through multi-stops yet. - `listItems` BookShipmentItem[], required: 1 to 100 items. Bounds: height 0.1-85, length 0.1-636, width 0.1-102, quantity 1-9999, totalWeight 0.01-80000. - `name` string - `height` number, required: Maximum 108 on POST /freights/booking; maximum 85 on POST /freights/freight-quote, /freights/book and the multi-stops endpoints (checked on the raw value, whatever the sizeUnit). - `length` number, required - `width` number, required - `sizeUnit` 'IN' | 'FT', required - `totalWeight` number, required - `weightUnit` 'lbs' | 'kgs', required - `quantity` integer, required - `packaging` string: Packaging unit of the line item (e.g. Pallet). Defaults to Pallet. - `temperature_limit` object: Temperature-controlled (reefer) freight is NOT supported yet by the quote endpoints: POST /freights/quote rejects any non-zero min/max and POST /freights/freight-quote rejects the field entirely with 400 `Reefer Shipment is not supported yet!`. Omit this field unless instructed otherwise by WARP. - `min` number: Minimum temperature. - `max` number: Maximum temperature. - `stackable` boolean - `notes` string - `freightClass` string: NMFC freight class of the line item (e.g. 70). - `barcodes` string[] - `pickupServices` PickupService[] - `quantity` number, required - `service` 'photo-required-pickup' | 'liftgate-pickup' | 'convention-trade-show-pickup' | 'inside-pickup' | 'limited-access-pickup' | 'residential-pickup' | 'construction-site-pickup' | 'pickup-appointment' | 'pickup-layover' | 'detention-shipper' | 'drop-empty' | 'driver-assist-pickup' | 'drop-and-hook-pickup' | 'inside-pickup-upstairs-mezzanine-trash-removal' | 'inside-pickup-back-side-of-the-house' | 'inside-pickup-living-space-garage', required: Pickup service options - `deliveryServices` DeliveryService[] - `quantity` number, required - `service` 'photo-required-delivery' | 'liftgate-delivery' | 'convention-trade-show-delivery' | 'inside-delivery' | 'limited-access-delivery' | 'residential-delivery' | 'construction-site-delivery' | 'delivery-appointment' | 'delivery-layover' | 'lumper' | 'detention-receiver' | 'redelivery' | 'drop-loaded' | 'driver-assist-delivery' | 'drop-and-hook-delivery' | 'inside-delivery-upstairs-mezzanine-trash-removal' | 'inside-delivery-back-side-of-the-house' | 'inside-delivery-living-space-garage', required: Delivery service options - `additionalServices` AdditionalService[] - `quantity` number, required - `service` 'photo-required' | 'sort-n-seg' | 'extra-stop' | 'extra-miles' | 'driver-assist' | 'notify' | 'check_calls' | 'otp_late_fee' | 'otd_late_fee' | 'carrier_otp' | 'carrier_otd' | 'tonu' | 'miscellaneous' | 'deduction' | 'racket_straps' | 'trailer_rental' | 'storage' | 'cross_dock_charge' | 'drop_loaded_equipment' | 'drop_and_hook' | 'drop_equipment' | 'reweigh_reclass' | 'insurance' | 'chassis_rental', required: Addtional service options - `shipmentType` 'FTL': Shipment type. Only FTL is accepted for multi-stops; any other value is rejected with 400. - `vehicleType` object - `code` 'DRY_VAN_53' | 'STRAIGHT_TRUCK_26' | 'CARGO_VAN', required ## Response `200` successful creation - MultiStopsQuoteResult - `quote_id` string: Unique quote ID (prefixed with WM, 28 characters). Use this ID when booking. Quotes created before the short ID rollout use the legacy PRICING_MULTI_ prefix and remain valid. - `total_charge` number: Total price for the entire multi-stop route in USD - `transit_time` number: Estimated transit time in seconds - `transit_time_without_team` number: Estimated transit time in seconds when the load is driven by a single driver instead of a team - `rate_detail` object: Detailed rate breakdown ## Other responses - `400`: validation error - `401`: Unauthorized - the apikey header is missing or does not match any active API key. - `403`: Forbidden - the customer account is suspended. The body carries `message` only, without `code`. - `429`: Too Many Requests - the quoting rate limit of the API key was exceeded (only POST /freights/quote, /freights/freight-quote and /freights/quote/multi-stops are rate limited; limits apply per UTC hour and per UTC day). The `Retry-After` header holds the number of seconds until the window resets. - `500`: Internal Server Error - an unknown error has occurred. --- [API](https://skmtc.dev/wearewarp/apis/warp-api-documentation.md) · [All operations](https://skmtc.dev/wearewarp/apis/warp-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/wearewarp/apis/warp-api-documentation/revisions/01526741bb48?raw)