# Get Rate

Retrieve shipping rates for a given package and address.  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.phone` (string)
    Recipient's phone number. Required for international shipments.
    Example: 1237771234

  - `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](appendix.md) for supported values.
    Example: ["usps_small_flat_rate_box"]

  - `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"

  - `shipments.contents.origin_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"

  - `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](appendix.md) 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

  - `order.tax_ids.tax_id_country` (string)
    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"

  - `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

  - `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.

  - `options.hazmat_code` (string)
    Specifies the type of hazardous material for DHL eCommerce shipments. This parameter must be used in conjunction with options.require_hazmat to take effect.
    Enum: "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.

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

  - `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