Batch Quote

Use this endpoint to quote up to 500 shipments in a single request. Each shipment is quoted independently; failures are captured per-shipment (partial success). Returns a quoteId for each successful quote that can later be added to a batch and booked.

Quotes expire after 30 days.

REST Endpoint

POST /restapi/v1/customers/:customerId/batch-quote

Request Content Type

application/json

Request JSON Example

POST /restapi/v1/customers/TEST00002/batch-quote

{
  "shipments": [
    {
      "carrierCode": "ups",
      "serviceCode": "ups_ground",
      "packageTypeCode": "ups_custom_package",
      "shipmentDate": "2026-04-15",
      "shipmentReference": "order-1001",
      "contentDescription": "Electronics",
      "sender": {
        "name": "Albert Jones",
        "company": "Jones Co.",
        "address1": "123 Some Street",
        "address2": "",
        "city": "Holladay",
        "state": "UT",
        "zip": "84117",
        "country": "US",
        "phone": "8015042351",
        "email": "sender@test.com"
      },
      "receiver": {
        "name": "Alice Jensen",
        "company": "",
        "address1": "54 Green St.",
        "address2": "",
        "city": "Salt Lake City",
        "state": "UT",
        "zip": "84106",
        "country": "US",
        "phone": "8013920046"
      },
      "residential": true,
      "signatureOptionCode": null,
      "weightUnit": "lb",
      "dimUnit": "in",
      "currency": "USD",
      "pieces": [
        {
          "weight": "2.5",
          "length": "10",
          "width": "8",
          "height": "4",
          "insuranceAmount": null,
          "declaredValue": null
        }
      ],
      "billing": {
        "party": "sender"
      },
      "providerAccountId": null
    },
    {
      "carrierCode": "usps",
      "serviceCode": "usps_priority",
      "packageTypeCode": "usps_custom_package",
      "shipmentDate": "2026-04-15",
      "shipmentReference": "order-1002",
      "contentDescription": "Books",
      "sender": {
        "name": "Albert Jones",
        "company": "Jones Co.",
        "address1": "123 Some Street",
        "address2": "",
        "city": "Holladay",
        "state": "UT",
        "zip": "84117",
        "country": "US",
        "phone": "8015042351"
      },
      "receiver": {
        "name": "Bob Smith",
        "company": "",
        "address1": "789 Elm Ave",
        "address2": "",
        "city": "Provo",
        "state": "UT",
        "zip": "84601",
        "country": "US",
        "phone": "8019876543"
      },
      "residential": true,
      "signatureOptionCode": null,
      "weightUnit": "lb",
      "dimUnit": "in",
      "currency": "USD",
      "pieces": [
        {
          "weight": "1.0",
          "length": "12",
          "width": "9",
          "height": "3",
          "insuranceAmount": null,
          "declaredValue": null
        }
      ],
      "billing": {
        "party": "sender"
      },
      "providerAccountId": null
    }
  ]
}

Explanation of Request Fields

Field	JSON Type	Required	Description
shipments	array	true	Array of shipment objects to quote. Maximum 500 per request.
shipments[n].carrierCode	string	false	The carrier code. If empty or omitted, all available carriers are quoted.
shipments[n].serviceCode	string	false	The service code. If empty or omitted, all available services are quoted.
shipments[n].packageTypeCode	string	false	The package type code. If empty or omitted, quoted for all available package types.
shipments[n].shipmentDate	string	true	Shipment date in YYYY-MM-DD format
shipments[n].shipmentReference	string	true	Customer-provided reference for the shipment
shipments[n].contentDescription	string	false	Content description, often required for international
shipments[n].sender	object	true	Sender address (same fields as the Quote endpoint)
shipments[n].receiver	object	true	Receiver address (same fields as the Quote endpoint)
shipments[n].residential	boolean	false	Whether the receiver address is residential
shipments[n].signatureOptionCode	string or null	false	Signature option code, null for no signature
shipments[n].weightUnit	string	true	"lb", "oz", "kg", or "g"
shipments[n].dimUnit	string or null	true	"in" or "cm", null if package type has preset dimensions
shipments[n].currency	string	true	Currency code (USD, GBP, CAD, EUR)
shipments[n].pieces	array	true	Array of piece objects with weight and dimensions
shipments[n].billing	object	false	Billing configuration
shipments[n].providerAccountId	string or null	false	Provider Account ID

See the Quote endpoint for full details on sender, receiver, pieces, and billing fields.

Response Status Code

200 OK

Response Content Type

application/json

Response JSON Example

{
  "results": [
    {
      "shipmentIndex": 0,
      "status": "success",
      "quotes": [
        {
          "quoteId": 1234,
          "carrierCode": "ups",
          "serviceCode": "ups_ground",
          "serviceDescription": "UPS® Ground",
          "packageTypeCode": "ups_custom_package",
          "currency": "USD",
          "totalAmount": "16.27",
          "baseAmount": "12.15",
          "zone": "2",
          "quotedWeight": "3",
          "quotedWeightType": "Actual",
          "surcharges": [
            {
              "description": "Residential surcharge",
              "amount": "4.12"
            }
          ]
        }
      ]
    },
    {
      "shipmentIndex": 1,
      "status": "error",
      "error": "Invalid zip code for destination",
      "errorCategory": "INVALID_REQUEST"
    }
  ]
}

Explanation of Response Fields

Field	Type	Description
results	array	One entry per shipment in the request, in the same order
results[n].shipmentIndex	integer	Zero-based index corresponding to the input shipments array
results[n].status	string	"success" or "error"
results[n].quotes	array	Array of quote results (only present when status is "success"). Contains one quote when serviceCode is specified, or multiple when quoting all available services.
results[n].quotes[n].quoteId	integer	System-generated quote ID. Use this ID to add the quote to a batch.
results[n].quotes[n].carrierCode	string	The carrier code
results[n].quotes[n].serviceCode	string	The service code
results[n].quotes[n].serviceDescription	string	Human-readable service description
results[n].quotes[n].packageTypeCode	string	The package type code
results[n].quotes[n].currency	string	Currency code
results[n].quotes[n].totalAmount	decimal	Total quoted amount including surcharges
results[n].quotes[n].baseAmount	decimal	Base charge amount
results[n].quotes[n].zone	string	The zone used to compute the shipping cost
results[n].quotes[n].quotedWeight	string	The weight used for quoting
results[n].quotes[n].quotedWeightType	string	"Actual" or "Dimensional"
results[n].quotes[n].surcharges	array	Array of surcharge objects
results[n].quotes[n].surcharges[n].description	string	Human-readable surcharge description
results[n].quotes[n].surcharges[n].amount	decimal	Surcharge amount
results[n].error	string	Error message (only present when status is "error")
results[n].errorCategory	string	Error category code (only present when status is "error")

Notes

• Each shipment is quoted independently. If one shipment fails, the others will still be quoted.
• The quoteId returned for each successful quote is used with the batch management endpoints (Create Batch, Add to Batch) and the Batch Book endpoint.
• Quotes expire after 30 days. Expired quotes cannot be booked.
• Maximum of 500 shipments per request.