# Get Rate

Retrieve shipping rates for a given package and address. </br> **Rate limit:** 600 requests per minute.

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

## Request fields (application/json):

  - `request_id` (string)
    Unique identifier for this API request. Used for tracking, debugging, and issue resolution. Must be a string up to 64 characters.
    Example: req_20251024_abcd1234ef567890

  - `carrier` (object)
    Carrier information

  - `carrier.carrier_token` (string)
    Please refer to your ShipSaving account Carrier Accounts -> Token
    Example: ca_36f49ebbe91d4006a6583e17ceeec500

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

  - `from.name` (string, required)
    Example: full name

  - `from.company` (string)
    Example: company name

  - `from.email` (string)
    Example: xxx@gmail.com

  - `from.phone` (string)
    Shipper's phone number. Required for international shipments.
    Example: 1237771234

  - `from.street` (string, required)
    Example: xxx Grand Ave

  - `from.street2` (string)
    Optional secondary address line (e.g., Apt, Suite, Unit, Floor).
    Example: Apt 5B

  - `from.city` (string, required)
    Example: Los Angeles

  - `from.state` (string, required)
    Example: CA

  - `from.zip` (string, required)
    Example: 90018

  - `from.country` (string, required)
    2-letter code for origin 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` (object, required)
    Recipient's address

  - `to.name` (string, required)
    Example: full name

  - `to.company` (string)
    Example: company name

  - `to.email` (string)
    Example: xxx@gmail.com

  - `to.phone` (string)
    Recipient's phone number. Required for international shipments.
    Example: 1237771234

  - `to.street` (string, required)
    Example: xxx Grand Ave

  - `to.city` (string, required)
    Example: Los Angeles

  - `to.state` (string, required)
    Example: CA

  - `to.zip` (string, required)
    Example: 90018

  - `to.residential` (boolean)
    Specifies if the address is residential, which can impact the quoted shipping rate.
    Example: true

  - `shipments` (array, required)
    List of shipments

  - `shipments.length` (number, required)
    Package length (inch)
    Example: 6

  - `shipments.width` (number, required)
    Package width (inch)
    Example: 6

  - `shipments.height` (number, required)
    Package height (inch)
    Example: 6

  - `shipments.weight` (number, required)
    Package weight (pound)
    Example: 1

  - `shipments.packages` (array)
    This field accepts carrier predefined packages.  Please refer to the [Predefined Carrier Packages Table](/v1/appendix) for supported values.

  - `shipments.insurance_amount` (number)
    Amount for insured shipment. Must be used in conjunction with insurance_provider.
    Example: 120

  - `shipments.custom_print1` (string)
    Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.
    Example: custom print1

  - `shipments.custom_print2` (string)
    Customized print on label.If the label itself supports custom printing content, this field will be printed onto the label.
    Example: custom print2

  - `shipments.contents` (array)
    List of items filed for customs (*required for international)

  - `shipments.contents.weight` (number, required)
    Weight of the item in lbs.
    Example: 1

  - `shipments.contents.description` (string, required)
    Description of the item being shipped. Provide accurate and clear details for customs clearance.
    Example: T-shirt

  - `shipments.contents.quantity` (integer, required)
    Total number of identical items in this shipment entry.
    Example: 2

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

  - `shipments.contents.hs_tariff_number` (string)
    Harmonized System (HS) tariff code of the item.
    Example: 610910

  - `order` (object)
    Order information

  - `order.warehouse_name` (string, required)
    Pre-existing warehouse name in ShipSaving system. (Please refer to your ShipSaving account Warehouses -> Name)
    Example: WH

  - `order.store_name` (string)
    Pre-existing store name in ShipSaving system. (Please refer to your ShipSaving account Stores -> Stores Nickname. If you use order_number, then the store_name of the order is required)

  - `order.order_number` (string)
    Pre-existing order number in ShipSaving system. If you need to check label price or buy a label for an order which already existed in our system, then this field is required.

  - `order.status` (string)
    Used with order_number; sets order status (awaiting, hold, or shipped) after label purchase. Defaults to awaiting if omitted.
    Enum: "awaiting", "hold", "shipped"

  - `order.service_type` (string)
    Please refer to the [Carrier Service Types Table](/v1/appendix) for supported values.
    Example: usps_ground_advantage

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

  - `order.insurance_provider` (string)
    Used with the field insurance_amount.
    Enum: "SHIPSURANCE", "CARRIER"

  - `order.contents_type` (string)
    Enum: "GIFT", "MERCHANDISE", "SAMPLE", "RETURNED_GOODS", "DOCUMENTS"

  - `order.non_delivery_option` (string)
    Defines the action to take for undeliverable shipments.
    Enum: "RETURN", "ABANDON"

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

  - `order.eel_pfc_code` (string)
    EEI filing identifier for this shipment.  
Provide either the Internal Transaction Number (ITN) received from AES, or the exemption code if EEI filing is not required.
    Example: X20250627012345

  - `order.tax_ids` (array)
    recipient‘s taxid

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

  - `order.tax_ids.tax_id_number` (string)
    The value corresponding to the tax ID type

  - `options` (object)
    Additional shipping options

  - `options.ship_date` (string)
    Timestamp in ISO 8601 format, including local time and time zone offset.
    Example: 2024-02-07T10:55:56-08:00

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

  - `options.require_hazmat` (boolean)
    Whether this shipment contains dangerous goods or hazardous materials (USPS Ground Advantage service only). View [tutorial](https://www.uspsdelivers.com/hazmat-shipping-safety/) about how to package, label and ship HAZMAT for domestic shipments.
    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)
    The possible values are "pdf" or "png". If this parameter is not provided, the default value is "png".
    Enum: "png", "pdf"

  - `options.require_qr_code` (boolean)
    Indicates whether the shipping label should be generated as a normal label, QR code or barcode.   Set to `true` to request a paperless label (e.g., QR code or barcode).   Note: Availability of paperless labels depends on the carrier's support.
    Example: false

  - `recipient_tax_ids` (array)
    Recipient's tax information

  - `recipient_tax_ids.tax_id_type` (string)
    Enum: "TIN", "EIN", "SSN", "VAT", "EORI", "IOSS", "PAN", "VOEC"

  - `recipient_tax_ids.tax_id_number` (string)
    recipient_tax_ids parameter

## Response 200 fields (application/json):

  - `rates` (array)
    List of shipment rates

  - `rates.shipment_id` (string)
    Example: ship_bea6cc8c-27f8-4dcf-915e-f6aeed8c5600

  - `rates.rate_id` (string)
    Example: rate_e50d02e2-047a-402c-aa32-22ad0926db00

  - `rates.provider` (string)
    Carrier account provider, ShipSaving or user's own account
    Example: shipsaving

  - `rates.account_name` (string)
    Example: USPS

  - `rates.carrier` (string)
    Carrier, USPS, UPS, FEDEX, or DHL
    Example: USPS

  - `rates.service` (string)
    Example: USPS_GROUND_ADVANTAGE

  - `rates.service_type` (string)
    Example: usps_ground_advantage

  - `rates.package` (string)
    Example: PACKAGE

  - `rates.package_type` (string)
    Example: my_package

  - `rates.delivery_days` (string)
    Course of traveling days to destination
    Example: 5

  - `rates.published_rate` (number)
    Standard shipping rate before discount
    Example: 10.9

  - `rates.rate` (number)
    Actual shipping rate after discount
    Example: 8.99

  - `rates.rebate` (number)
    Example: 0.21