Rates

Rate shop across your configured carrier accounts to find the best shipping options for a given package and destination. Save rate quotes as immutable snapshots for later use in operations.

Get Rates

POST/api/v1/rates

Get shipping rates from one or more carrier accounts.

Requiredrates:read

Queries one or more carrier accounts for available shipping rates based on the package details, origin, and destination. If multiple carrier accounts match, rates are returned grouped by carrier.

Request Body

Field	Type	Required	Description
`shipFrom`	object	Yes	Origin address
`shipTo`	object	Yes	Destination address
`packages`	object[]	Yes	Package dimensions and weight
`shipDate`	string	No	Requested ship date (ISO 8601, defaults to today)
`serviceType`	string	No	Filter to a specific service type
`carrier`	string	No	Filter to a specific carrier code
`carrierAccountId`	string	No	Use a specific carrier account
`residential`	boolean	No	Whether the destination is residential

Address Object

Field	Type	Required	Description
`address1`	string	Yes	Street address line 1
`address2`	string	No	Street address line 2
`city`	string	Yes	City
`province`	string	No	State or province name
`provinceCode`	string	No	State or province code
`country`	string	No	Country name
`countryCode`	string	Yes	Two-letter country code
`zip`	string	Yes	Postal code

Package Object

Field	Type	Required	Description
`weight`	object	Yes	Weight object with `value` (number) and `unit` (`lb` or `kg`)
`length`	number	No	Length
`width`	number	No	Width
`height`	number	No	Height
`dimensionUnit`	string	No	Dimension unit: `in` or `cm` (default: `in`)


curl -X POST "https://api.orderly-hub.com/api/v1/rates" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "shipFrom": {
      "address1": "123 Warehouse St",
      "city": "Newark",
      "provinceCode": "NJ",
      "zip": "07102",
      "countryCode": "US"
    },
    "shipTo": {
      "address1": "456 Customer Ave",
      "city": "Los Angeles",
      "provinceCode": "CA",
      "zip": "90001",
      "countryCode": "US"
    },
    "packages": [
      { "weight": { "value": 2.5, "unit": "lb" } }
    ]
  }'

Response (Single Carrier)


{
  "rates": [
    {
      "serviceType": "GROUND_HOME_DELIVERY",
      "serviceName": "FedEx Ground Home Delivery",
      "totalPrice": 8.95,
      "currency": "USD",
      "transitDays": 5,
      "estimatedDelivery": "2026-01-20"
    }
  ],
  "carrier": "fedex",
  "carrierAccountId": "uuid"
}

Response (Multi Carrier)


{
  "results": [
    {
      "rates": [...],
      "carrier": "fedex",
      "carrierAccountId": "uuid"
    },
    {
      "rates": [...],
      "carrier": "ups",
      "carrierAccountId": "uuid"
    }
  ],
  "errors": [
    {
      "carrier": "usps",
      "carrierAccountId": "uuid",
      "error": "Service temporarily unavailable"
    }
  ]
}

Get Rates from Order

POST/api/v1/rates/from-order/:orderId

Get shipping rates using an existing order's addresses and line items.

Requiredrates:read

Automatically builds a rate request from a saved order’s shipping address and line items. Useful for getting rates without manually extracting address and package data.

Path Parameters

Parameter	Type	Description
`orderId`	string	The order UUID to rate

Request Body (Optional Overrides)

Field	Type	Required	Description
`carrier`	string	No	Filter to a specific carrier code
`carrierAccountId`	string	No	Use a specific carrier account


curl -X POST "https://api.orderly-hub.com/api/v1/rates/from-order/660e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "fedex"
  }'

Response

Same response format as Get Rates above.

Create Rate Snapshot

POST/api/v1/rates/snapshots

Save an immutable rate quote for use in operations.

Requiredrates:read

Saves a rate quote as an immutable snapshot. Rate snapshots are useful for locking in a quoted rate before creating a shipment, or for auditing purposes.

Request Body

Field	Type	Required	Description
`carrierAccountId`	string	Yes	Carrier account that provided the rate
`carrier`	string	Yes	Carrier code (e.g., `fedex`, `ups`)
`serviceType`	string	Yes	Service type code
`serviceName`	string	Yes	Human-readable service name
`totalPrice`	number	Yes	Total quoted price
`currency`	string	Yes	Currency code (e.g., `USD`)
`breakdown`	object	No	Cost breakdown details
`transitDays`	number	No	Estimated transit days
`transitDaysGuaranteed`	boolean	No	Whether transit days are guaranteed (default: `false`)
`estimatedDelivery`	string	No	Estimated delivery date (ISO 8601)
`deliveryByTime`	string	No	Delivery-by time (e.g., `10:30 AM`)
`shipFrom`	object	Yes	Origin address
`shipTo`	object	Yes	Destination address
`packages`	object[]	Yes	Package details
`expiresAt`	string	No	When the quote expires (ISO 8601)
`rawResponse`	object	No	Raw carrier response for reference


curl -X POST "https://api.orderly-hub.com/api/v1/rates/snapshots" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "carrierAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "carrier": "fedex",
    "serviceType": "GROUND_HOME_DELIVERY",
    "serviceName": "FedEx Ground Home Delivery",
    "totalPrice": 8.95,
    "currency": "USD",
    "transitDays": 5,
    "shipFrom": {
      "address1": "123 Warehouse St",
      "city": "Newark",
      "provinceCode": "NJ",
      "zip": "07102",
      "countryCode": "US"
    },
    "shipTo": {
      "address1": "456 Customer Ave",
      "city": "Los Angeles",
      "provinceCode": "CA",
      "zip": "90001",
      "countryCode": "US"
    },
    "packages": [
      { "weight": { "value": 2.5, "unit": "lb" } }
    ],
    "expiresAt": "2026-01-20T00:00:00Z"
  }'

Response (201)


{
  "data": {
    "id": "uuid",
    "organizationId": "uuid",
    "carrierAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "carrier": "fedex",
    "serviceType": "GROUND_HOME_DELIVERY",
    "serviceName": "FedEx Ground Home Delivery",
    "totalPrice": 8.95,
    "currency": "USD",
    "transitDays": 5,
    "transitDaysGuaranteed": false,
    "shipFrom": { "address1": "123 Warehouse St", "city": "Newark" },
    "shipTo": { "address1": "456 Customer Ave", "city": "Los Angeles" },
    "packages": [{ "weight": { "value": 2.5, "unit": "lb" } }],
    "quotedAt": "2026-01-15T10:00:00Z",
    "expiresAt": "2026-01-20T00:00:00Z",
    "createdAt": "2026-01-15T10:00:00Z"
  }
}

Get Rate Snapshot

GET/api/v1/rates/snapshots/:id

Retrieve a saved rate snapshot by ID.

Requiredrates:read

Returns the full details of a previously saved rate snapshot.

Path Parameters

Parameter	Type	Description
`id`	string	Rate snapshot UUID


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

Response


{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "organizationId": "uuid",
    "carrierAccountId": "uuid",
    "carrier": "fedex",
    "serviceType": "GROUND_HOME_DELIVERY",
    "serviceName": "FedEx Ground Home Delivery",
    "totalPrice": 8.95,
    "currency": "USD",
    "transitDays": 5,
    "transitDaysGuaranteed": false,
    "shipFrom": { "address1": "123 Warehouse St", "city": "Newark" },
    "shipTo": { "address1": "456 Customer Ave", "city": "Los Angeles" },
    "packages": [{ "weight": { "value": 2.5, "unit": "lb" } }],
    "quotedAt": "2026-01-15T10:00:00Z",
    "expiresAt": "2026-01-20T00:00:00Z",
    "createdAt": "2026-01-15T10:00:00Z"
  }
}

Error Responses

Status	Description
`404`	Rate snapshot not found
`400`	No active carrier accounts found
`502`	Carrier API error (all carriers failed)