# Get Rates

Retrieves shipping rates from all active carriers and service levels under your account, optionally filtered by specified carriers and service levels, and returns results sorted by fastest, cheapest, and other criteria along with any applicable error information.

Endpoint: POST /api/shipment/get_rates
Version: v2
Security: BearerAuth

## Request fields (application/json):

  - `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_X", "FEDEX_X", "DHL_A", "GOFO_EXPRESS_A", "SWIFTX", "UPS_CANADA"

  - `shipment_rate_carrier_data.service_levels` (array)
    Carrier service levels.

  - `custom_data` (object)
    custom data

  - `custom_data.signing_person` (string)
    Name of the individual signing the customs form, typically the sender or an authorized agent, confirming that all declared information is accurate and compliant with applicable customs regulations.
    Example: Ray

  - `custom_data.content_type` (string)
    Enum: "merchandise", "documents", "return_merchandise", "sample", "gift"

  - `custom_data.tax_ids` (array)
    Sender's tax information

  - `custom_data.tax_ids.tax_id_type` (string)
    tax id type
    Enum: "TIN", "EIN", "SSN", "VAT", "EORI", "IOSS", "PAN"

  - `custom_data.tax_ids.tax_id_number` (string)
    tax id number
    Example: tin2888

  - `custom_data.tax_ids.country_code` (string)
    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

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

  - `custom_data.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: X20250719123456

  - `custom_data.undeliverable_option` (string)
    Defines the action to take for undeliverable shipments.
    Enum: "return_to_sender", "abandon"

  - `custom_data.item_data_list` (array)

  - `custom_data.item_data_list.description` (string)
    Description of the item being shipped. Provide accurate and clear details for customs clearance.
    Example: cloth

  - `custom_data.item_data_list.quantity` (integer)
    Total number of identical items in this shipment entry.
    Example: 10

  - `custom_data.item_data_list.origin` (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

  - `custom_data.item_data_list.weight` (number)
    Weight of the item in the selected unit.
    Example: 10

  - `custom_data.item_data_list.unit_cost` (number)
    Declared value of the item in USD. Refers to the unit price of the item.
    Example: 19.99

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

  - `custom_data.item_data_list.hs_tariff_number` (string)
    Harmonized System (HS) tariff code of the item. [Find My Harmonization Number.](https://uscensus.prod.3ceonline.com/ui/)
    Example: xx

## Response 200 fields (application/json):

  - `code` (string)
    Example: ok

  - `msg` (string)
    Example: ok

  - `data` (object)

  - `data.fastest` (object)

  - `data.fastest.zone` (string)
    Example: 8Rural

  - `data.fastest.currency` (string)
    Example: USD

  - `data.fastest.cubic` (boolean)
    Example: false

  - `data.fastest.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.fastest.carrier_code` (string)
    Carrier code identifier.
    Enum: "USPS", "UPS", "FEDEX", "DHL_EXPRESS", "SWIFTX", "GOFO_EXPRESS", "UPS_CANADA"

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

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

  - `data.fastest.service_level` (string)
    Example: USPS_MEDIA_MAIL

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

  - `data.fastest.returned_package_code` (string)
    Example: my_package

  - `data.fastest.delivery_days` (string)
    Example: 2

  - `data.fastest.delivery_date` (string)
    Example: 2025-08-08T00:00:00+08:00

  - `data.fastest.delivery_weekday` (string)
    Example: MONDAY

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

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

  - `data.fastest.origin_price` (number)
    Example: null

  - `data.fastest.retail_price` (number)
    Example: 8.7

  - `data.fastest.discount_text` (string)

  - `data.fastest.insurance_info` (string)

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

  - `data.fastest.saturday_delivery` (boolean)
    Example: false

  - `data.fastest.one_rate` (boolean)
    Example: false

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

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

  - `data.fastest.base_rate.currency` (string)
    Example: USD

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

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

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

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

  - `data.fastest.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.fastest.surcharges.category` (string)
    The category of the surcharge, grouping similar charge types together.
Common examples include `HANDLING`, `FUEL`, etc.
    Example: HANDLING

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

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

  - `data.fastest.surcharges.list_amount` (number)
    Example: 4

  - `data.fastest.surcharges.retail_amount` (number)
    Example: 4

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

  - `data.fastest.price_details` (array)
    A per-component breakdown of the rate. FedEx specific.

  - `data.fastest.price_details.code` (string)
    A code identifying the charge component.
Common examples include `BASE_CHARGE`, `FUEL`, `RESIDENTIAL_DELIVERY`,
`DEMAND_OVERSIZE`, `DEMAND`, `OVERSIZE`, and `DELIVERY_AREA`.
    Example: BASE_CHARGE

  - `data.fastest.price_details.description` (string)
    A human-readable description of the charge component.
    Example: Shipping Label Charge

  - `data.fastest.price_details.price` (number)
    The amount charged for this component.
    Example: 99.31

  - `data.shipment_rate_data` (array)

  - `data.error_info` (object)