Quote
Use this endpoint to quote shipping rates.
REST Endpoint
POST /restapi/v1/customers/:customerId/quote
Request Content Type
application/json
Request JSON Example
POST /restapi/v1/customers/TEST00002/quote
{
"carrierCode": "ups",
"serviceCode": "ups_ground",
"packageTypeCode": "ups_custom_package",
"shipmentDate": "2026-10-15",
"sender": {
"country": "US",
"zip": "84117"
},
"receiver": {
"city": "Salt Lake City",
"country": "US",
"zip": "84106",
"email":"foo@bar.com"
},
"residential": true,
"signatureOptionCode": "DIRECT",
"contentType": "goods",
"contentDescription": "stuff and things",
"weightUnit": "lb",
"dimUnit": "in",
"currency": "USD",
"customsCurrency": "USD",
"pieces": [
{
"weight": "1.4",
"length": "5.1",
"width": "4",
"height": "2.5",
"insuranceAmount": "12.15",
"declaredValue": null
}
],
"billing": {
"party": "sender"
},
"providerAccountId": null
}
Explanation of Request Fields
| Field | JSON Type | Required | Description |
|---|---|---|---|
| carrierCode | string | false | The carrier code |
| serviceCode | string | false | The service code |
| packageTypeCode | string | false | The package type code |
| shipmentDate | string | false | The date the shipment will ship, in YYYY-MM-DD format, date only. Defaults to the current date. Past dates are rejected by the carriers, and they limit how far ahead they accept (DHL 9 days, FedEx 10). Quoted amounts may differ for a future date |
| sender.city | string | false | Origin City/Town. Required when sender.zip is not given, for a country that does not use postal codes (e.g. HK) |
| sender.country | string | true | ISO two-character country code |
| sender.zip | string or null | false | Zip or postal code. Required for countries that use postal codes. Do not send a placeholder value such as 00000 for a country that has none |
| receiver.city | string | false | Destination City/Town |
| receiver.country | string | true | ISO two-character country code |
| receiver.zip | string or null | true | Zip or postal code |
| receiver.email | string | false | Receiver email address |
| residential | boolean | false | Set to true of the receiver address is residential |
| signatureOptionCode | string or null | true | Signature option code for shipment. Null for no signature |
| uspsExpressAmDelivery | boolean | false | 10:30 AM Delivery |
| saturdayDelivery | boolean | false | Saturday Delivery |
| contentType | string | false | Carrier specific content type. See Content Types. If not provided, defaults to the carrier's default content type |
| contentDescription | string | false | Content description for the shipment. Provide it for international shipments. If not provided, an empty string is used |
| weightUnit | string | true | "lb" for pounds, "oz" for ounces, "kg" for kilograms, or "g" for grams |
| dimUnit | string or null | true | Either "in" for inches or "cm" for centimeters or null if packageType has preset dimensions |
| currency | string | true | The currency of the provided insuranceAmount, declaredValue, and customsValue (if customsCurrency is not present) fields. (USD, GBP, CAD, EUR) |
| customsCurrency | string | true | If present, is the currency of the provided customsValue. (USD, GBP, CAD, EUR) |
| pieces[n].weight | decimal | true | Numeric weight as a JSON string |
| pieces[n].length | decimal or null | true | Numeric length as a JSON string (set to null if packageType has preset dimensions) |
| pieces[n].width | decimal or null | true | Numeric width as a JSON string (set to null if packageType has preset dimensions) |
| pieces[n].height | decimal or null | true | Numeric height as a JSON string (set to null if packageType has preset dimensions) |
| pieces[n].insuranceAmount | decimal or null | true | The value of the piece to be covered by insurance as a JSON string. Must be null for no insurance |
| pieces[n].declaredValue | decimal or null | true | The declared value of the piece for international shipments as a JSON string. Must be null for domestic shipments |
| billing.party | string | false | Billing party: "sender" for Sender, "receiver" for Receiver, "third_party" for Third Party |
| providerAccountId | string or null | false | Provider Account ID which can be retrieved using the List Provider Accounts endpoint |
Content Types
Each carrier accepts its own contentType values. Book Shipment uses the same values.
| Carrier | Accepted values |
|---|---|
| fedex | Sold, Not Sold, Gift, Sample, Repair and Return, Personal Effects |
| ups | goods, document |
| dhl | goods, document |
| canpar | goods, document |
| puro | goods, document |
| tnt | goods |
| asendia2 | merchandise, gift, document |
| usps | merchandise, document, gift, other, returnedGoods, commercialSample, humanitarianDonation, dangerousGoods |
| usps (EasyPost account) | merchandise, documents, gift, other, returned_goods, sample |
| globegistics | merchandise, document, gift, other, returnedGoods, commercialSample, humanitarianDonation, dangerousGoods |
FedEx also accepts these common values, so one contentType can quote every carrier:
| Value | FedEx value |
|---|---|
goods, merchandise |
Sold |
document, documents |
Not Sold |
gift |
Gift |
sample, commercialSample |
Sample |
FedEx values are not case sensitive, and _ can replace a space (for example, SOLD or NOT_SOLD).
Quote checks the value only for FedEx, and only for an international shipment. There, a value FedEx does not accept returns the error category INVALID_REQUEST for each FedEx service, and the other carriers still return rates. A domestic FedEx quote does not use the value, so it uses Sold in its place. Book Shipment checks the value for every carrier in the table above and returns INVALID_REQUEST for a value the carrier does not accept.
Response Status Code
200 OK
Response Content Type
application/json
Response JSON Example
{
"carrierCode": "ups",
"serviceCode": "ups_ground",
"packageTypeCode": "ups_custom_package",
"currency": "USD",
"customsCurrency": "USD",
"totalAmount": "16.27",
"baseAmount": "12.15",
"surcharges": [
{
"description": "Residential surcharge",
"amount": "4.12"
}
],
"zone": "2",
"quotedWeight": "2",
"quotedWeightType": "Actual",
"estimatedArrival": "2026-10-17"
}
Explanation of Response Fields
| Field | Type | Description |
|---|---|---|
| carrierCode | string | The carrier code |
| serviceCode | string | The service code |
| serviceDescription | string | The service description (only available when getting multiple quotes) |
| packageTypeCode | string | The package type code |
| currency | string | 3-character currency code |
| customsCurrency | string | 3-character currency code |
| totalAmount | decimal | Total quote amount (includes base charge and all surcharges) |
| baseAmount | decimal | Base charge amount |
| surcharges[n].description | string | Human readable description of surcharge |
| surcharges[n].amount | decimal | Surcharge amount |
| zone | string | The zone used to compute shipping cost |
| estimatedArrival | string | The carrier's estimated delivery date, calculated from the ship date. Omitted when the carrier supplies no estimate, which currently includes all USPS services. Format varies by carrier, so parse it as ISO 8601 |
| pieces[n].totalAmount | decimal | USPS Multipiece only. Total quote amount for piece, including base charge and all surcharges for piece |
| pieces[n].baseAmount | decimal | USPS Multipiece only. Base charge amount for piece |
| pieces[n].surcharges[n].description | string | USPS Multipiece only. Human readable description of piece surcharge |
| pieces[n].surcharges[n].amount | decimal | USPS multipiece only. Piece surcharge amount |
Quote Multiple Services
If you want to get back all available services instead of the price for a single service, you can call this same endpoint without specifying the serviceCode or packageTypeCode. The carrierCode is also optional, but can be used to return only services for a specific carrier.
Request JSON
{
"carrierCode": "ups",
"serviceCode": "",
"packageTypeCode": "",
"shipmentDate": "2026-10-15",
"sender": {
"country": "US",
"zip": "84117"
},
"receiver": {
"city": "Salt Lake City",
"country": "US",
"zip": "84106",
"email":"foo@bar.com"
},
"residential": true,
"signatureOptionCode": "DIRECT",
"contentType": "goods",
"contentDescription": "stuff and things",
"weightUnit": "lb",
"dimUnit": "in",
"currency": "USD",
"customsCurrency": "USD",
"pieces": [
{
"weight": "1.4",
"length": "5.1",
"width": "4",
"height": "2.5",
"insuranceAmount": "12.15",
"declaredValue": null
}
],
"billing": {
"party": "sender"
},
"providerAccountId": null
}
Response JSON
{
"quotes": [
{
"carrierCode": "ups",
"serviceCode": "ups_ground",
"serviceDescription": "UPSĀ® Ground",
"packageTypeCode": "ups_custom_package",
"currency": "USD",
"customsCurrency": "USD",
"totalAmount": "16.27",
"baseAmount": "12.15",
"surcharges": [
{
"description": "Residential surcharge",
"amount": "4.12"
}
],
"zone": "2",
"quotedWeight": "2",
"quotedWeightType": "Actual",
"estimatedArrival": "2026-10-17"
},
{
"carrierCode": "ups",
"serviceCode": "ups_second_day_air",
"serviceDescription": "UPS 2nd Day AirĀ®",
"packageTypeCode": "ups_custom_package",
"currency": "USD",
"totalAmount": "41.72",
"baseAmount": "22.66",
"surcharges": [
{
"description": "ResidentialExpress",
"amount": "5.15"
},
],
"zone": "202",
"quotedWeight": "2",
"quotedWeightType": "Actual",
"estimatedArrival": "2026-10-16"
},
]
}