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"
    },
  ]
}