# Get Rates

Retrieve available shipping rates for the given package dimensions, weight, and origin/destination addresses. Returns rates across all active carrier accounts, sorted by price.

Endpoint: POST /api/rates/list
Version: v1
Security: BearerAuth, ApiTokenAuth

## Request fields (application/json):

  - `from` (object, required)
    Shipper's (origin) address.

  - `from.name` (string, required)
    Full name of the contact.
    Example: John Doe

  - `from.company` (string)
    Company or organization name.
    Example: Acme Corp

  - `from.phone` (string)
    Phone number. Required for international shipments.
    Example: 2135551234

  - `from.email` (string)
    Email address.
    Example: john@example.com

  - `from.street` (string, required)
    Primary street address.
    Example: 1600 Amphitheatre Parkway

  - `from.street2` (string)
    Secondary address line (apt, suite, unit, etc.).
    Example: Suite 200

  - `from.city` (string, required)
    City name.
    Example: Mountain View

  - `from.state` (string, required)
    State or province abbreviation.
    Example: CA

  - `from.zip` (string, required)
    ZIP or postal code.
    Example: 94043

  - `from.country` (string, required)
    Two-letter country code per [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
    Example: US

  - `to` (any, required)
    Recipient's (destination) address.

  - `shipments` (array, required)
    One or more parcels to be rated.

  - `shipments.length` (number)
    Package length in inches.
    Example: 12

  - `shipments.width` (number)
    Package width in inches.
    Example: 8

  - `shipments.height` (number)
    Package height in inches.
    Example: 6

  - `shipments.weight` (number, required)
    Package weight in pounds.
    Example: 2.5

  - `shipments.packages` (array)
    Carrier predefined package types (e.g., `usps_small_flat_rate_box`).
    Example: ["usps_small_flat_rate_box"]

  - `shipments.insurance_amount` (number)
    Declared value for shipment insurance in USD. Must be used with `order.insurance_provider`.
    Example: 150

  - `shipments.custom_print1` (string)
    First line of custom text printed on the label (carrier support required).
    Example: Order #12345

  - `shipments.custom_print2` (string)
    Second line of custom text printed on the label (carrier support required).
    Example: Fragile

  - `shipments.contents` (array)
    Customs line items. Required for international shipments.

  - `shipments.contents.weight` (number, required)
    Item weight in pounds.
    Example: 0.5

  - `shipments.contents.description` (string, required)
    Description of the item for customs clearance.
    Example: Cotton T-Shirt

  - `shipments.contents.quantity` (integer, required)
    Number of identical items.
    Example: 2

  - `shipments.contents.value` (number, required)
    Declared unit value in USD.
    Example: 29.99

  - `shipments.contents.hs_tariff_number` (string)
    Harmonized System (HS) tariff code. See [USITC HTS](https://hts.usitc.gov/) for reference.
    Example: 610910

  - `order` (object)

  - `order.warehouse_name` (string, required)
    Warehouse name as listed in your ShipSaving dashboard (Warehouses > Name).
    Example: WH

  - `order.store_name` (string)
    Store nickname as listed in your ShipSaving dashboard (Stores > Store Nickname). Required when `order_number` is provided.
    Example: My Shopify Store

  - `order.order_number` (string)
    Existing order number in ShipSaving. When provided, the label is linked to this order.
    Example: 20240201125047532

  - `order.status` (string)
    Order status to set after label purchase.
    Enum: "awaiting", "hold", "shipped"

  - `order.service_type` (string)
    Carrier service type code (e.g., `usps_ground_advantage`, `ups_ground`).
    Example: usps_ground_advantage

  - `order.signature` (string)
    Signature confirmation level.
    Enum: "NO_SIGNATURE", "SIGNATURE", "ADULT_SIGNATURE"

  - `order.insurance_provider` (string)
    Insurance provider. Must be used with `shipments[].insurance_amount`.
    Enum: "SHIPSURANCE", "CARRIER"

  - `order.contents_type` (string)
    Customs contents category for international shipments.
    Enum: "GIFT", "MERCHANDISE", "SAMPLE", "RETURNED_GOODS", "DOCUMENTS"

  - `order.non_delivery_option` (string)
    Action for undeliverable shipments.
    Enum: "RETURN", "ABANDON"

  - `order.eel_pfc_type` (string)
    Electronic Export Information (EEI) filing method. `ITN` if an Internal Transaction Number was obtained via AES; `EXEMPTION_CODE` if the shipment qualifies for an EEI exemption.
    Enum: "ITN", "EXEMPTION_CODE"

  - `order.eel_pfc_code` (string)
    ITN or exemption code corresponding to `eel_pfc_type`.
    Example: X20250627012345

  - `order.tax_ids` (array)
    Tax identification numbers associated with the order.

  - `order.tax_ids.tax_id_type` (string)
    Type of tax identification number.
    Enum: "TIN", "EIN", "SSN", "VAT", "EORI", "IOSS", "PAN", "VOEC"

  - `order.tax_ids.tax_id_number` (string)
    Tax identification number value.
    Example: IM1234567890

  - `options` (object)

  - `options.ship_date` (string)
    Ship date in ISO 8601 format with timezone offset.
    Example: 2025-02-07T10:55:56-08:00

  - `options.require_saturday_delivery` (boolean)
    Whether this shipment requires Saturday delivery.
    Example: false

  - `options.require_hazmat` (boolean)
    Whether the shipment contains hazardous materials. Currently supported for USPS Ground Advantage and DHL eCommerce.
    Example: false

  - `options.hazmat_code` (string)
    Specifies the type of hazardous material. Use `usps_hazmat_820` for USPS shipments (Class 9 lithium batteries, unmarked package) and the `dhlecs_*` values for DHL eCommerce shipments. Shipments to or from U.S. offshore destinations (such as Guam, Puerto Rico) generally require `usps_hazmat_820` in order to ship lithium batteries. This parameter must be used in conjunction with `options.require_hazmat` to take effect.
    Enum: "usps_hazmat_820", "dhlecs_lithium_metal_alloy_contained", "dhlecs_lithium_metal_alloy_packed", "dhlecs_lithium_metal_alloy_standalone", "dhlecs_lithium_ion_contained", "dhlecs_lithium_ion_packed", "dhlecs_lithium_ion_standalone", "dhlecs_limited_quantity", "dhlecs_small_quantity_provision", "dhlecs_limited_quantities_plt"

  - `options.label_type` (string)
    Label output format.
    Enum: "png", "pdf"

  - `options.require_qr_code` (boolean)
    Request a paperless label (QR code or barcode) instead of a standard label. Availability depends on carrier support.
    Example: false

  - `seller_id` (string)
    Caller-defined unique identifier for a merchant or seller.
This is an open field — you may pass any value that uniquely identifies
a merchant on your platform (e.g., your internal merchant ID).
At least one of `seller_id` or `carrier_account_id` must be provided.
When `carrier_account_id` is also provided, `carrier_account_id` takes priority
for account matching.
**Note:** If the `seller_id` is not associated with a UPS 4th-party account,
rate quotes will still be returned, but label purchase will fail.
    Example: merchant_10042

  - `carrier_account_id` (string)
    Carrier account token in ShipSaving. You can obtain this value from the response of the Create Ghost Account endpoint,
or from the ShipSaving system → Carrier Accounts page (the "Token" column in the list).
At least one of `seller_id` or `carrier_account_id` must be provided.
When both are provided, `carrier_account_id` takes priority.
**Note:** If the `carrier_account_id` is not associated with a UPS 4th-party account,
rate quotes will still be returned, but label purchase will fail.
    Example: ca_bc28f2e7aaaa4bbbacccbf7d9f2c27xx

  - `recipient_tax_ids` (array)
    Recipient tax identification numbers for customs.

## Response 200 fields (application/json):

  - `shipment_id` (string)
    Shipment identifier for this rate group.
    Example: ship_bea6cc8c-27f8-4dcf-915e-f6aeed8c5600

  - `rate_id` (string)
    Unique rate identifier. Pass this to **Buy Label** to purchase.
    Example: rate_e50d02e2-047a-402c-aa32-22ad0926db00

  - `provider` (string)
    Account provider — `shipsaving` (discounted) or `user` (own account).
    Example: shipsaving

  - `account_name` (string)
    Carrier account display name.
    Example: USPS

  - `carrier` (string)
    Carrier name (USPS, UPS, FedEx, DHL, etc.).
    Example: USPS

  - `service` (string)
    Service level name in uppercase.
    Example: USPS_GROUND_ADVANTAGE

  - `service_type` (string)
    Service level code in lowercase.
    Example: usps_ground_advantage

  - `package` (string)
    Package type name in uppercase.
    Example: PACKAGE

  - `package_type` (string)
    Package type code in lowercase.
    Example: my_package

  - `delivery_days` (integer)
    Estimated transit time in business days.
    Example: 5

  - `published_rate` (number)
    Carrier's retail (list) rate before any discount.
    Example: 10.9

  - `rate` (number)
    Your discounted rate.
    Example: 8.99

  - `rebate` (number)
    Rebate amount credited back after purchase.
    Example: 0.21

  - `insurance_fee` (number)
    Insurance fee if insurance was requested.
    Example: 0

  - `zone` (string)
    Carrier shipping zone.
    Example: 4

  - `is_saturday_delivery` (boolean)
    Whether the rate includes Saturday delivery.
    Example: false

## Response 400 fields (application/json):

  - `message` (string)
    Human-readable error message.
    Example: Invalid request parameters.