Shipping rate quotes: quotes carrier rates for one lane.
POST
/api/shipping/rate-quotes
deprecated
Requires: Shipping.RateQuotes, merchant scope.
The quote runs through the merchant's own shipping provider binding. The request names a saved ship-from origin or supplies one inline, names saved parcel presets or supplies parcels inline, and gives the destination. The response carries the outcome and, on success, the rate options. A merchant with no enabled shipping provider receives the `NotConfigured` outcome rather than an error. Quotes are rate limited per merchant; a caller over the ceiling receives `Shipping:QuoteRateLimitExceeded` with HTTP 429. An inline parcel whose weight is not above zero and at most 100,000, or whose length, width or height is not above zero and at most 10,000, is refused with HTTP 400: each failing measure is a `validationErrors` entry on `parcels[n].Weight`, `parcels[n].Length`, `parcels[n].Width` or `parcels[n].Height` carrying the code `Shipping:ParcelMeasureOutOfRange`.
Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.
Example request
Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.
The request body is a ShippingRateQuoteRequestDto. See the Request body section below for its fields.
Parameters
Request body
application/json
, required
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
merchantId
required |
string (uuid) | The merchant the quote is for. The caller must be authorized over this merchant; an API key
quotes only for the merchant it belongs to.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
originId
required |
string (uuid) | The id of a saved ship-from origin belonging to the merchant. Give this or `origin`,
not both.
Conditional: When OriginId is not null.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
origin
required |
Address Address | A ship-from address supplied inline, for a quote from a location the merchant has not saved.
Give this or `originId`, not both.
Conditional: When Origin is not null.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
Fields of Address:
This body has no documented fields. | ||||||||||||||||||||||||||||||||||||||
destination
required |
Address Address | The address the parcels ship to.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
Fields of Address:
This body has no documented fields. | ||||||||||||||||||||||||||||||||||||||
destinationIsResidential
required |
boolean | Whether the destination is a residence. Some carriers price residential delivery differently;
leave unset when unknown and the provider applies its own default.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
parcelPresetIds
required |
array of string (uuid) array of | The ids of saved parcel presets belonging to the merchant, one per parcel in the shipment. Give
this or `parcels`, not both.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
parcels
required |
array of ShippingRateQuoteParcelDto array of ShippingRateQuoteParcelDto | The parcels supplied inline, one per parcel in the shipment. Give this or
`parcelPresetIds`, not both.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
Fields of each ShippingRateQuoteParcelDto:
This body has no documented fields. | ||||||||||||||||||||||||||||||||||||||
carriers
required |
array of string array of | Optional provider-specific carrier account identifiers to restrict the quote to. When omitted the
provider quotes every carrier the binding allows.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
serviceLevels
required |
array of string array of | Optional provider-specific service level tokens to restrict the quote to. When omitted the provider
returns every service level the binding allows.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
currency
required |
string | The ISO 4217 currency the quotes should be expressed in. When omitted the platform's configured
default currency is requested.
Conditional: When Currency is not empty.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||||||||||||||||||||||||
This request body has no documented fields.
Responses
200 OK
Body:
ShippingRateQuoteResultDto
ShippingRateQuoteResultDto
Each item has these fields.
| Field | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
outcome
required |
ShippingRateOutcome ShippingRateOutcome | What happened. `quotes` carries options only when this is `Success`.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| |||||||||||||||||||||||||||
isSuccess
required |
boolean | Whether `outcome` is `Success`.
read only
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| |||||||||||||||||||||||||||
providerName
required |
string | The name of the provider that answered. The platform's fallback provider answers when the
merchant has no enabled binding, with the outcome `NotConfigured`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| |||||||||||||||||||||||||||
quoteId
required |
string (uuid) | The identifier the platform recorded this quote under, when the outcome is success. A checkout
that lets a shopper choose a service sends this identifier and the chosen option's
`optionId` back, never an amount: the server re-reads the
recorded quote and charges the amount it stored. Absent for a non-success outcome.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| |||||||||||||||||||||||||||
expiresAt
required |
string (date-time) | When the recorded quote stops being honored, in UTC. A selection submitted after this instant
is refused and the lane has to be quoted again. Absent when `quoteId` is absent.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| |||||||||||||||||||||||||||
quotes
required |
array of ShippingRateQuoteDto array of ShippingRateQuoteDto | The rate options, ordered as the provider returned them. Empty unless the outcome is success.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| |||||||||||||||||||||||||||
Fields of each ShippingRateQuoteDto:
This body has no documented fields. | |||||||||||||||||||||||||||||
messages
required |
array of string array of | Provider or platform messages explaining a non-success outcome. Never carries a credential, a
URL or a raw exception.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| |||||||||||||||||||||||||||
This response has no documented body fields.
403 Forbidden
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo RemoteServiceErrorInfo |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This response has no documented body fields.
401 Unauthorized
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo RemoteServiceErrorInfo |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This response has no documented body fields.
400 Bad Request
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo RemoteServiceErrorInfo |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This response has no documented body fields.
404 Not Found
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo RemoteServiceErrorInfo |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This response has no documented body fields.
501 Not Implemented
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo RemoteServiceErrorInfo |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This response has no documented body fields.
500 Internal Server Error
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo RemoteServiceErrorInfo |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This response has no documented body fields.
default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take. The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take.
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo RemoteServiceErrorInfo |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This response has no documented body fields.
429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause.
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo RemoteServiceErrorInfo |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This response has no documented body fields.
Errors
A failed request returns the platform error envelope. The
error reference lists every value
error.code can carry and shows the four response shapes.