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,
          "lineItems": [
            {
              "sku": "ABC-123",
              "productName": "Blue Widget",
              "quantity": 2
            }
          ]
        }
      ],
      "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].pieces[n].lineItems	array or null	false	Optional line items for the piece. Preserve order and duplicates.
shipments[n].pieces[n].lineItems[n].sku	string	true	SKU (may be empty string)
shipments[n].pieces[n].lineItems[n].productName	string	true	Product name
shipments[n].pieces[n].lineItems[n].quantity	integer	true	Quantity
shipments[n].billing	object	false	Billing configuration
shipments[n].providerAccountId	string or null	false	Provider Account ID
shipments[n].commercialInvoice	object or null	false	Commercial invoice details for international shipments (same fields as the Book Shipment endpoint)
shipments[n].commercialInvoice.senderTaxIdNumberType	string	false	Type of the sender's tax ID number (senderVatTaxId). One of ein (Employer Identification Number), dns (DUNS), or fgn (foreign tax ID). Defaults to ein if omitted. Used for UPS international shipments.
shipments[n].commercialInvoice.dhlTaxIds	array	false	Up to two DHL Express commercial-invoice tax IDs (e.g. an EORI number for EU customs clearance). Only consumed by DHL Express; ignored by other carriers. To send an EORI, add an entry with type set to EOR.
shipments[n].commercialInvoice.dhlTaxIds[n].number	string	true	The tax-id value (for an EORI, the EORI number). Must be non-empty.
shipments[n].commercialInvoice.dhlTaxIds[n].type	string	true	Tax-id type code. Must be one of EOR (EORI), VAT, FTZ, CNP, EIN, or FED
shipments[n].commercialInvoice.dhlTaxIds[n].issuerCountry	string	false	ISO two-character country code of the tax-id issuer

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

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"
            }
          ]
        }
      ],
      "quoteErrors": [
        {
          "carrierCode": "usps",
          "serviceCode": "usps_priority",
          "serviceDescription": "USPS Priority Mail®",
          "packageTypeCode": "usps_custom_package",
          "error": "USPS requires the sender name to include both first and last name.",
          "errorCategory": "INVALID_REQUEST"
        }
      ]
    },
    {
      "shipmentIndex": 1,
      "status": "error",
      "error": "The total weight of items on the Commercial Invoice exceeds the shipment weight. Please update either the package weight or the item quantities and weights so they are consistent.",
      "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". "error" means the whole shipment could not be quoted; "success" means the shipment was processed and its per-service results are in quotes and quoteErrors.
results[n].quotes	array	Successful (priced, bookable) quotes (only present when status is "success"). Contains one entry when serviceCode is specified, or one per available service otherwise.
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].quoteErrors	array	Services that could not be quoted (only present when status is "success"). Each entry identifies the service and the reason it failed.
results[n].quoteErrors[n].carrierCode	string	The carrier code
results[n].quoteErrors[n].serviceCode	string	The service code
results[n].quoteErrors[n].serviceDescription	string	Human-readable service description
results[n].quoteErrors[n].packageTypeCode	string	The package type code
results[n].quoteErrors[n].error	string	Reason the service couldn't be quoted
results[n].quoteErrors[n].errorCategory	string	Error category code
results[n].error	string	Error message (only present when the shipment-level status is "error")
results[n].errorCategory	string	Error category code (only present when the shipment-level status is "error")

Notes

• Each shipment is quoted independently. If one shipment fails, the others will still be quoted.
• If a shipment includes a commercial invoice whose item weights total more than the shipment's package weight, the entire shipment fails with a shipment-level error (errorCategory INVALID_REQUEST) and is not 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.

Changelog

Date	Notes
2026-06-29	Added commercialInvoice.dhlTaxIds[n].number/type/issuerCountry for sending DHL Express tax IDs, including an EORI number (type = EOR) for EU customs clearance
2026-07-01	Added commercialInvoice.senderTaxIdNumberType (was already supported by the schema and backend)