Get a cost and transit-time estimate without creating an order. Built for cart and checkout previews, quoting tools, and any flow that needs a price before an order exists.
GET
{licensee-url}/api/shipping
This is a GET request. All inputs are passed as query-string parameters. There is no request body.
No authentication required
This quoting endpoint does not require an Authorization header. Replace {licensee-url} with your Grasshopper environment host.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| method | string | Required | Rating method for the quote. Use weight to rate by total shipment weight. |
| zip | string | Required | Destination ZIP code the shipment is being quoted to. |
| weight | number | Required | Total shipment weight in pounds. Required when method=weight. |
| service_level | string | Required | Service level code, for example wg. See the full list of service level codes. |
| pickup_region | string | Required | Origin / pickup region, given as a ZIP code. Determines the linehaul origin for the rate. |
| retailer_identifier | string | Required | The retailer account the quote is priced under. Rates and coverage are resolved against this retailer's contract. |
Example request
curl --location '{licensee-url}/api/shipping?method=weight&zip=78701&weight=150&service_level=wg&pickup_region=90066&retailer_identifier=ennovationhub' \
--header 'Content-Type: application/json'The same call, broken down:
| Value in example | Meaning |
|---|---|
| method=weight | Rate by total weight |
| zip=78701 | Deliver to Austin, TX 78701 |
| weight=150 | 150 lb shipment |
| service_level=wg | White Glove service |
| pickup_region=90066 | Pick up from the 90066 (Los Angeles) region |
| retailer_identifier=ennovationhub | Price under the "ennovationhub" retailer account |
Response
A successful request returns 200 OK with status: "ok". The quoted price is data.total_cost: the base cost plus all applicable accessorial fees.
{
"status": "ok",
"data": {
"cost": 252,
"message": "",
"errorCode": 0,
"last_mile_terminal": {
"name": "TX (Houston) Terminal",
"address": {
"address1": "3503 Polk Street",
"address2": "Ste. 3509",
"city": "Houston",
"state": "TX",
"zip": "77003",
"longitude": -95.3447573,
"latitude": 29.7418493,
"timezone": null,
"country": "US"
}
},
"accessorial_fees": {
"third_man_cost": { "success": true, "cost": 0, "count": 0 },
"fuel_surcharge": {
"success": true,
"cost": 36.54,
"steps": [ "Fuel Surcharge (14.5% on 252): 36.54" ],
"rate": 14.5
},
"disposition_cost": { "success": false, "cost": 0 },
"pre_inspection_cost": { "success": false, "cost": 0 },
"insurance_cost": {
"success": true,
"cost": 0,
"requested_coverage": 0,
"built_in_coverage": 337.5,
"approved_coverage": 337.5
},
"packaging_cost": { "success": true, "cost": 0, "steps": [] }
},
"fsc": true,
"pricing_set_id": "6a3d302c0ae0cf49cb8a14ec",
"base_cost": 252,
"total_accessorial_fees": 36.54,
"total_cost": 288.54,
"zip_info": {
"zipcode": "78701",
"city": "Austin",
"state": "TX",
"country": "US",
"lat": 30.271158,
"long": -97.741701,
"timezone": "America/Chicago",
"distance_to_hub": 148.019892765,
"valid": true
}
}
}Response fields
The fields you will use most when presenting a quote:
| Field | Type | Description |
|---|---|---|
| status | string | "ok" when the quote succeeds. |
| data.base_cost | number | Base linehaul cost before accessorial fees. |
| data.total_accessorial_fees | number | Sum of all applicable accessorial fees. |
| data.total_cost | number | The quoted price to show the customer. Equals base_cost plus total_accessorial_fees. |
| data.fsc | boolean | Whether a fuel surcharge was applied. |
| data.accessorial_fees | object | Per-fee breakdown. Each entry has success and cost; some add detail (fuel_surcharge.rate, insurance_cost.approved_coverage). |
| data.last_mile_terminal | object | The terminal that will handle the final mile, with name and address. |
| data.zip_info | object | Resolved destination detail, including distance_to_hub (miles) and the mapped region. |
| data.pricing_set_id | string | Identifier of the pricing set used to rate this quote. |
Errors
Responses use an envelope. A successful quote returns status: "ok" with data.errorCode: 0 and an empty data.message. When a quote cannot be produced, data.errorCode is non-zero and data.message carries the reason. Common causes:
| Condition | What it means |
|---|---|
| Missing parameter | A required query parameter (for example weight or service_level) was not supplied. |
| ZIP not covered | The destination ZIP is not in the coverage network for this service level. |
| Unknown service level | The service_level code is not recognized. See the list of service level codes. |
| Unknown retailer | The retailer_identifier does not resolve to a retailer account. |