API Reference
Developer Guide
Rate Quote endpoint
All rate requests use a single endpoint regardless of platform. The platform is identified via the X-Platform request header, which the first-party plugins set automatically.
POST /api/v1/quotes
Content-Type: application/json
x-api-key: YOUR_API_KEY
X-Platform: magento2 | shopify | bigcommerce | customThe full OpenAPI specification is available in the interactive Swagger UI.
Request payload
{
"dest_country_id": "GB", // ISO 3166-1 alpha-2 country code
"dest_region_code": "ENG", // State / county / province
"dest_postcode": "SW1A 1AA", // Postal / ZIP code
"dest_city": "London", // Destination city
"package_weight": 2.5, // Total cart weight (store weight unit)
"package_value": 49.99, // Total declared cart value
"items": [
{
"sku": "WIDGET-001",
"name": "Blue Widget",
"qty": 2,
"price": 24.99, // Unit base price
"weight": 1.25, // Unit weight
"tags": ["fragile"] // ShipRateAPI routing tags (may be empty)
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
dest_country_id | string | Yes | ISO 3166-1 alpha-2 country code (e.g. GB, US) |
dest_region_code | string | No | State or region code — used for zone matching |
dest_postcode | string | Yes | Postal or ZIP code — primary zone matching key |
dest_city | string | No | Destination city name |
package_weight | number | Yes | Total shipment weight in your store's configured unit |
package_value | number | No | Declared value — used for insurance and free-shipping rules |
items | array | Yes | Line items in the cart (see item fields below) |
Item fields
| Field | Type | Description |
|---|---|---|
sku | string | Product SKU |
name | string | Product name |
qty | number | Quantity ordered |
price | number | Unit base price |
weight | number | Unit weight |
tags | string[] | Routing tags — see Tags & Routing |
Response format
A 200 OK response is an array of rate objects. Only display rates where available is true.
[
{
"available": true,
"carrier_title": "Royal Mail",
"method_code": "RM_tracked_48",
"method_title": "Tracked 48",
"amount": 3.99,
"base_amount": 3.99
},
{
"available": false,
"carrier_title": "DPD",
"method_code": "DPD_next_day",
"method_title": "Next Day",
"amount": 0,
"base_amount": 0
}
]| Field | Type | Description |
|---|---|---|
available | boolean | Whether this method can be offered. Filter out false entries before presenting to customers. |
carrier_title | string | Display name for the carrier (e.g. Royal Mail) |
method_code | string | Stable, machine-readable method identifier — safe to store against an order |
method_title | string | Display name for the shipping method (e.g. Tracked 48) |
amount | number | Price shown to the customer, after any markup rules |
base_amount | number | Raw carrier cost before markup — useful for margin reporting |
Error codes
| Status | Meaning |
|---|---|
200 | Success — response is an array of rate objects (may be empty if no carriers matched) |
400 | Malformed request — check required fields are present and correctly typed |
401 | Missing or invalid x-api-key |
403 | API key revoked or suspended |
429 | Monthly request limit reached for your plan |
500 | Internal server error — check the health status page for ongoing incidents |