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",
  "sender": {
    "country": "US",
    "zip": "84117"
  },
  "receiver": {
    "city": "Salt Lake City",
    "country": "US",
    "zip": "84106",
    "email":"foo@bar.com"
  },
  "residential": true,
  "signatureOptionCode": "DIRECT",
  "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
sender.country	string	true	ISO two-character country code
sender.zip	string or null	true	Zip or postal code
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	false	Signature option code for shipment. Null for no signature
uspsExpressAmDelivery	boolean	false	10:30 AM Delivery
saturdayDelivery	boolean	false	Saturday Delivery
contentDescription	string	false	Content Description must be a string. Can be empty. Often required for international shipments
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

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

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
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": "",
  "sender": {
    "country": "US",
    "zip": "84117"
  },
  "receiver": {
    "city": "Salt Lake City",
    "country": "US",
    "zip": "84106",
    "email":"foo@bar.com"
  },
  "residential": true,
  "signatureOptionCode": "DIRECT",
  "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"
    },
    {
        "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"
    },
  ]
}