# Batch Quick Rate

This endpoint allows you to quickly retrieve shipment rate quotes by providing the from_address_data, to_address_data, package_data and the ship_date.

Each API call can include up to 10 individual rate requests.

Previously, this endpoint only returned rates for USPS Ground Advantage.
With the new update, you may optionally specify additional carriers and service levels using the shipment_rate_carrier_data field. A detailed explanation of how to use this parameter can be found in the request schema.

- If shipment_rate_carrier_data is omitted:
The system will return rates only for USPS Ground Advantage (default behavior).

- If shipment_rate_carrier_data is provided:
The system will return rates only for the specified provider(s) and service level(s).
Multiple combinations may be sent in a single request.

Endpoint: POST /api/shipment/batch/quick_rate
Version: v2
Security: BearerAuth

## Request fields (application/json):

  - `request_unique_id` (string, required)
    A unique identifier generated by the requesting client to mark a single rate request within a batch. This value will be echoed back in the corresponding response, ensuring one-to-one mapping between requests.
    Example: "unique_uuid_001"

  - `from_address_data` (object, required)

  - `from_address_data.first_name` (string, required)
    First Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.
    Example: "Alice"

  - `from_address_data.last_name` (string, required)
    Last Name corresponding to the address. For the Batch Quick Rate API, this parameter is optional.
    Example: "Green"

  - `from_address_data.company_name` (string)
    Firm/business name corresponding to the address.
    Example: "ShipSaving"

  - `from_address_data.phone` (string)
    Phone number of the sender/recipient. Required for international shipments. Providing a phone number is highly recommended for all shipments to ensure accurate delivery and facilitate carrier contact if needed.
    Example: 1234567890

  - `from_address_data.email` (string)
    Email address of the sender/recipient. May be used by the carrier for delivery notifications or issue resolution.
    Example: "support@shipsaving.com"

  - `from_address_data.street` (string, required)
    The number of a building along with the name of the road or street on which it is located.
    Example: "xxxx Olive Street"

  - `from_address_data.street2` (string)
    The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.
    Example: "STE XXX"

  - `from_address_data.city` (string, required)
    This is the city name of the address.
    Example: "Los Angeles"

  - `from_address_data.state` (string, required)
    - For U.S. addresses, this field must be a valid two-letter state code (e.g., "CA" for California, "NY" for New York).
- For non-U.S. addresses, there is no restriction on the value.
    Example: "CA"

  - `from_address_data.zip_code` (string, required)
    Postal code of an Address.
    Example: "021XX"

  - `from_address_data.country` (string, required)
    2-letter code for country. This field’s value will be an [ISO 3166-1 two-digit code](https://en.wikipedia.org/wiki/ISO_3166-1).
    Example: "US"

  - `to_address_data` (object, required)

  - `to_address_data.address_type` (string, required)
    Indicates whether the destination address is residential or commercial.
This flag is used to determine carrier-specific surcharges (e.g., UPS residential delivery fees).
    Enum: "residential", "commercial"

  - `package_data` (object, required)

  - `package_data.type` (string)
    Defines the type of package being shipped.
- my_package: Use when specifying custom package dimensions. Requires width, length, height, dimension_unit, weight, and weight_unit.
- predefined: Use when selecting a carrier’s predefined package type. Requires carrier_package_code and weight fields only; dimension fields are ignored.
    Enum: "my_package", "predefined"

  - `package_data.length` (number)
    Length of the package in the selected unit.
    Example: 10

  - `package_data.width` (number)
    Width of the package in the selected unit.
    Example: 10

  - `package_data.height` (number)
    Height of the package in the selected unit.
    Example: 10

  - `package_data.weight` (number)
    Weight of the package in the selected unit.
    Example: 10

  - `package_data.carrier_package_code` (string)
    Carrier package code identifier. See [Appendix - Carrier Package Codes](../../../../appendix.md) for supported values in the ShipSaving New API (v2).
    Enum: "USPS_LETTER", "USPS_LARGE_ENVELOPE_OR_FLAT", "USPS_THICK_ENVELOPE", "USPS_SMALL_FLAT_RATE_BOX", "USPS_MEDIUM_FLAT_RATE_BOX", "USPS_LARGE_FLAT_RATE_BOX", "USPS_FLAT_RATE_ENVELOPE", "USPS_PADDED_FLAT_RATE_ENVELOPE", "USPS_LEGAL_FLAT_RATE_ENVELOPE", "UPS_LETTER", "UPS_25KG_BOX", "UPS_10KG_BOX", "UPS_TUBE", "UPS_PAK", "UPS_EXPRESS_BOX_SMALL", "UPS_EXPRESS_BOX_MEDIUM", "UPS_EXPRESS_BOX_LARGE", "FEDEX_ENVELOPE", "FEDEX_PAK", "FEDEX_TUBE", "FEDEX_EXTRA_SMALL_BOX", "FEDEX_SMALL_BOX", "FEDEX_MEDIUM_BOX", "FEDEX_LARGE_BOX", "FEDEX_EXTRA_LARGE_BOX", "FEDEX_BOX", "FEDEX_10KG_BOX", "FEDEX_25KG_BOX", "UPS_CANADA_LETTER", "UPS_CANADA_25KG_BOX", "UPS_CANADA_10KG_BOX", "UPS_CANADA_TUBE", "UPS_CANADA_PAK", "UPS_CANADA_EXPRESS_BOX_SMALL", "UPS_CANADA_EXPRESS_BOX_MEDIUM", "UPS_CANADA_EXPRESS_BOX_LARGE", "UPS_CANADA_EXPRESS_BOX"

  - `package_data.dimension_unit` (string)
    Selected dimension unit.
    Enum: "in", "cm"

  - `package_data.weight_unit` (string)
    Selected weight unit.
    Enum: "lb", "oz", "kg", "g"

  - `option_data` (object)
    Additional shipping options

  - `option_data.signature` (string)
    Request standard or adult signature confirmation.
    Enum: "signature", "adult_signature"

  - `option_data.custom_text_on_label_1` (string)
    Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.
    Example: "Please put the package in the locker."

  - `option_data.custom_text_on_label_2` (string)
    Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.
    Example: "Please put the package in the locker."

  - `option_data.hazardous_materials` (boolean)
    Whether this shipment contains dangerous goods or hazardous materials (USPS Ground Advantage service only). View tutorial about how to package, label and ship HAZMAT for domestic shipments.
    Example: true

  - `option_data.additional_handling` (boolean)
    Indicates whether the package requires additional handling due to size, weight, or packaging that falls outside standard shipping guidelines. Carriers may apply extra fees when this is set to true.

  - `option_data.require_saturday_delivery` (boolean)
    When true, only returns rate quotes that support Saturday delivery. If false or omitted, all available rate quotes are returned regardless of Saturday delivery support.

Note: 
- Actual Saturday delivery availability depends on the carrier and service level — some carriers or services may not support it. 
- Enabling this preference may result in additional carrier surcharges or higher shipping costs if the selected service level applies extra fees for Saturday delivery.

  - `ship_date` (string, required)
    Timestamp in ISO 8601 format, including local time and time zone offset.
    Example: "2025-07-31T00:00:00+08:00"

  - `shipment_rate_carrier_data` (array)
    Specifying this parameter allows you to filter rates by carrier and service level, enabling faster queries.

  - `shipment_rate_carrier_data.provider_id` (string)
    carrier provider id
    Enum: "UPS_SS_DNI", "USPS_B", "FEDEX_X", "DHL_A", "GOFO_EXPRESS_A", "SWIFTX", "UPS_CANADA"

  - `shipment_rate_carrier_data.service_levels` (array)
    Carrier service levels.
    Enum: "USPS_FIRST_CLASS_MAIL", "USPS_GROUND_ADVANTAGE", "USPS_PRIORITY_MAIL", "USPS_PRIORITY_MAIL_EXPRESS", "USPS_MEDIA_MAIL", "USPS_LIBRARY_MAIL", "USPS_FIRST_CLASS_MAIL_INTERNATIONAL", "USPS_PRIORITY_MAIL_INTERNATIONAL", "USPS_PRIORITY_MAIL_EXPRESS_INTERNATIONAL", "UPS_GROUND", "UPS_GROUND_SAVER", "UPS_NEXT_DAY_AIR", "UPS_NEXT_DAY_AIR_SAVER", "UPS_NEXT_DAY_AIR_EARLY", "UPS_2ND_DAY_AIR", "UPS_2ND_DAY_AIR_AM", "UPS_3_DAY_SELECT", "UPS_STANDARD", "UPS_WORLDWIDE_SAVER", "UPS_WORLDWIDE_EXPRESS", "UPS_WORLDWIDE_EXPRESS_PLUS", "UPS_WORLDWIDE_EXPEDITED", "UPS_SUREPOST_LESS_THAN_1_LB", "UPS_SUREPOST_1_LB_OR_GREATER", "FEDEX_GROUND", "FEDEX_2_DAY", "FEDEX_2_DAY_AM", "FEDEX_EXPRESS_SAVER", "FEDEX_STANDARD_OVERNIGHT", "FEDEX_FIRST_OVERNIGHT", "FEDEX_PRIORITY_OVERNIGHT", "FEDEX_INTERNATIONAL_ECONOMY", "FEDEX_INTERNATIONAL_FIRST", "FEDEX_INTERNATIONAL_PRIORITY", "FEDEX_HOME_DELIVERY", "FEDEX_SMARTPOST", "FEDEX_STANDARD_OVERNIGHT_EXTRA_HOURS", "FEDEX_FIRST_OVERNIGHT_EXTRA_HOURS", "FEDEX_PRIORITY_OVERNIGHT_EXTRA_HOURS", "FEDEX_INTERNATIONAL_PRIORITY_EXPRESS", "FEDEX_INTERNATIONAL_CONNECT_PLUS", "FEDEX_DATE_CERTAIN_HOME_DELIVERY", "FEDEX_EVENING_HOME_DELIVERY", "FEDEX_APPOINTMENT_HOME_DELIVERY", "FEDEX_INTERNATIONAL_PRIORITY_PR", "DHL_EXPRESS_WORLDWIDE_B2C", "DHL_EXPRESS_WORLDWIDE_B2C_NONDOC", "DHL_EXPRESS_JET_LINE_NONDOC", "DHL_EXPRESS_SPRINT_LINE", "DHL_EXPRESS_EURO_PACK_DOC", "DHL_EXPRESS_BREAK_BULK_EXPRESS", "DHL_EXPRESS_MEDICAL_EXPRESS", "DHL_EXPRESS_WORLDWIDE_DOC", "DHL_EXPRESS_0900_NONDOC", "DHL_EXPRESS_FREIGHT_WORLDWIDE_NONDOC", "DHL_EXPRESS_DOMESTIC_ECONOMY_SELECT", "DHL_EXPRESS_ECONOMY_SELECT_NONDOC", "DHL_EXPRESS_DOMESTIC_EXPRESS_0900", "DHL_EXPRESS_JUMBO_BOX_NONDOC", "DHL_EXPRESS_0900", "DHL_EXPRESS_1030", "DHL_EXPRESS_1030_NONDOC", "DHL_EXPRESS_DOMESTIC_EXPRESS", "DHL_EXPRESS_DOMESTIC_EXPRESS_1030", "DHL_EXPRESS_WORLDWIDE_NONDOC", "DHL_EXPRESS_MEDICAL_EXPRESS_NODOC", "DHL_EXPRESS_GLOBAL_MAIL_BUSINESS", "DHL_EXPRESS_SAME_DAY", "DHL_EXPRESS_1200_DOC", "DHL_EXPRESS_WORLDWIDE_ECX", "DHL_EXPRESS_EURO_PACK_NONDOC", "DHL_EXPRESS_ECONOMY_SELECT", "DHL_EXPRESS_ENVELOPE", "DHL_EXPRESS_1200_NONDOC", "DHL_EXPRESS_DOMESTIC_EXPRESS_1200", "GOFO_EXPRESS_ECO", "SWIFTX_EXP", "UPS_CANADA_EXPEDITED", "UPS_CANADA_EXPRESS_EARLY", "UPS_CANADA_EXPRESS_SAVER", "UPS_CANADA_EXPRESS", "UPS_CANADA_STANDARD", "UPS_CANADA_3_DAY_SELECT", "UPS_CANADA_EXPRESS_EARLY_SM", "UPS_CANADA_WORLDWIDE_EXPEDITED_SM", "UPS_CANADA_WORLDWIDE_EXPRESS_PLUS_SM", "UPS_CANADA_WORLDWIDE_EXPRESS_SM", "UPS_CANADA_EXPRESS_SAVER_SM"

## Response 200 fields (application/json):

  - `code` (string)
    Example: "ok"

  - `msg` (string)
    Example: "ok"

  - `data` (array)

  - `data.request_unique_id` (string)
    A unique identifier generated by the requesting client to mark a single rate request within a batch. This value will be echoed back in the corresponding response, ensuring one-to-one mapping between requests.
    Example: "unique_uuid_001"

  - `data.shipment_rate_data` (array)

  - `data.shipment_rate_data.zone` (string,null)
    Example: "8Rural"

  - `data.shipment_rate_data.currency` (string)
    Example: "USD"

  - `data.shipment_rate_data.cubic` (boolean)

  - `data.shipment_rate_data.rate_id` (string)
    The unique identifier of a shipping rate returned by the get_rates endpoint. Use this value to reference a specific rate when purchasing a label.
    Example: "dc288147-f7dd-494d-9353-5ce00020c7aa"

  - `data.shipment_rate_data.carrier_code` (string)
    Carrier code identifier.
    Enum: "USPS", "UPS", "FEDEX", "DHL_EXPRESS", "SWIFTX", "GOFO_EXPRESS", "UPS_CANADA"

  - `data.shipment_rate_data.provider_id` (string)
    carrier provider id
    Enum: "UPS_SS_DNI", "USPS_B", "FEDEX_X", "DHL_A", "GOFO_EXPRESS_A", "SWIFTX", "UPS_CANADA"

  - `data.shipment_rate_data.service_name` (string)
    Example: "USPS Media Mail"

  - `data.shipment_rate_data.service_level` (string)
    Example: "USPS_MEDIA_MAIL"

  - `data.shipment_rate_data.service_level_desc` (string)
    Example: "A cost-effective way to send eligible books, media, and educational materials."

  - `data.shipment_rate_data.returned_package_code` (string,null)
    Example: "my_package"

  - `data.shipment_rate_data.delivery_days` (string,null)
    Example: 2

  - `data.shipment_rate_data.delivery_date` (string,null)
    Example: "2025-08-08T00:00:00+08:00"

  - `data.shipment_rate_data.delivery_weekday` (string,null)
    Example: "MONDAY"

  - `data.shipment_rate_data.service_detail` (string,null)
    Example: "Low rates for packages with expected delivery in 2-5 business days."

  - `data.shipment_rate_data.price` (number)
    Example: 5.91

  - `data.shipment_rate_data.origin_price` (number,null)

  - `data.shipment_rate_data.retail_price` (number,null)
    Example: 8.7

  - `data.shipment_rate_data.discount_text` (string,null)

  - `data.shipment_rate_data.insurance_info` (string,null)

  - `data.shipment_rate_data.ship_date` (string)
    Timestamp in ISO 8601 format, including local time and time zone offset.
    Example: "2025-07-31T00:00:00+08:00"

  - `data.shipment_rate_data.saturday_delivery` (boolean)

  - `data.shipment_rate_data.one_rate` (boolean)

  - `data.shipment_rate_data.base_rate` (object)
    Represents the base rate charged by a carrier for a given service level.

  - `data.shipment_rate_data.base_rate.amount` (number)
    Example: 33.21

  - `data.shipment_rate_data.base_rate.list_amount` (number)
    Example: 33.21

  - `data.shipment_rate_data.base_rate.retail_amount` (number)
    Example: 59.55

  - `data.shipment_rate_data.surcharges` (object,null)
    Represents a single surcharge item applied to a shipment or rate.

  - `data.shipment_rate_data.surcharges.object` (string)
    The object type, indicating this represents a surcharge item.

  - `data.shipment_rate_data.surcharges.type` (string)
    A code identifying the specific surcharge type.
For example, nonstandard_22 may indicate a non-standard package handling fee.
    Example: "nonstandard_22"

  - `data.shipment_rate_data.surcharges.category` (string)
    The category of the surcharge, grouping similar charge types together.
Common examples include HANDLING, FUEL, etc.
    Example: "HANDLING"

  - `data.shipment_rate_data.surcharges.amount` (number)
    The total surcharge amount charged for this item.
    Example: 4

  - `data.shipment_rate_data.surcharges.currency` (string)
    The three-letter currency code (ISO 4217) for the surcharge.
    Example: "USD"

  - `data.shipment_rate_data.usps_dim_rate_type` (string)
    Example: "dim-weight"

  - `data.error_info` (object)