Rate Comparisons

Compare your current shipping rates against alternative carriers. Import tracking numbers, track shipments, get alternative rates, and calculate potential savings.

List Rate Comparisons

GET/api/v1/rate-comparisons

List all rate comparisons with filtering and pagination.

Requiredrate-compare:read

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `draft`, `processing`, `completed`, `failed`, `cancelled`


curl -X GET "https://api.orderly-hub.com/api/v1/rate-comparisons?status=completed" \
  -H "Authorization: Bearer oh_..."

Get Rate Comparison

GET/api/v1/rate-comparisons/:id

Retrieve a single rate comparison by ID.

Requiredrate-compare:read


curl -X GET "https://api.orderly-hub.com/api/v1/rate-comparisons/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Create Rate Comparison

POST/api/v1/rate-comparisons

Create a new rate comparison with tracking numbers to analyze.

Requiredrate-compare:write

Request Body

Field	Type	Required	Description
`name`	string	Yes	Name for this comparison (1-255 chars)
`carrierAccountId`	string	Yes	Carrier account to compare rates against
`sourceCarrier`	string	Yes	Original carrier: `fedex` or `ups`
`items`	array	Yes	Tracking numbers to compare (1-10,000)
`items[].trackingNumber`	string	Yes	Tracking number (1-100 chars)
`items[].netCost`	number	No	Original cost paid
`items[].serviceType`	string	No	Original service type


curl -X POST "https://api.orderly-hub.com/api/v1/rate-comparisons" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "January FedEx vs UPS",
    "carrierAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceCarrier": "fedex",
    "items": [
      { "trackingNumber": "794644790132", "netCost": 12.50, "serviceType": "Ground" },
      { "trackingNumber": "794644790133", "netCost": 8.75 }
    ]
  }'

Delete Rate Comparison

DELETE/api/v1/rate-comparisons/:id

Delete a rate comparison.

Requiredrate-compare:write


curl -X DELETE "https://api.orderly-hub.com/api/v1/rate-comparisons/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Process Rate Comparison

POST/api/v1/rate-comparisons/:id/process

Start async processing — tracks shipments, gets rates, calculates savings.

Requiredrate-compare:write

Processing runs asynchronously via QStash. Poll the comparison status to track progress.


curl -X POST "https://api.orderly-hub.com/api/v1/rate-comparisons/550e8400-e29b-41d4-a716-446655440000/process" \
  -H "Authorization: Bearer oh_..."

Get Comparison Items

GET/api/v1/rate-comparisons/:id/items

List items in a rate comparison with filtering.

Requiredrate-compare:read

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50, max: 100)
`status`	string	Filter: `pending`, `tracking`, `rating`, `completed`, `failed`, `skipped`
`zone`	string	Filter by shipping zone
`serviceType`	string	Filter by service type
`search`	string	Search by tracking number


curl -X GET "https://api.orderly-hub.com/api/v1/rate-comparisons/550e8400-e29b-41d4-a716-446655440000/items?status=completed&limit=50" \
  -H "Authorization: Bearer oh_..."

Get Comparison Summary

GET/api/v1/rate-comparisons/:id/summary

Get aggregated summary with savings calculations.

Requiredrate-compare:read

Returns zone-level and service-level aggregations with total savings calculations.


curl -X GET "https://api.orderly-hub.com/api/v1/rate-comparisons/550e8400-e29b-41d4-a716-446655440000/summary" \
  -H "Authorization: Bearer oh_..."