---
title: "Generate a live rates request"
method: POST
path: "/live-rates"
tags: ["Rates at Checkout"]
---

# Generate a live rates request

`POST /live-rates`

Initiates a live rates request. Include either the object ID for
an existing address record or a fully formed address object when entering
an address value. You can also enter the object ID of an existing user parcel
template or a fully formed user parcel template object as the parcel value.

## Headers

- `SHIPPO-API-VERSION` string

## Request body

- LiveRateCreateRequest
  - `address_from` union — The sender address, which includes your name, company name, street address, city, state, zip code, country, phone number, and email address (strings). Special characters should not be included in any address element, especially name, company, and email.
    - string — Object ID for an existing [Address](/shippoapi/public-api/addresses)
    - AddressCompleteCreateRequest — Address represents the address as retrieved from the database
      - `name` string, required — **required for purchase** First and Last Name of the addressee **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Either company or name required; No length validation (first 35 chars printed on label) |
      - `company` string — Company Name **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 35 characters; Either company or name required |
      - `street1` string, required — **required for purchase** First street line. Usually street number and street name (except for DHL Germany, see street_no). **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
      - `street2` string — Second street line. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
      - `street3` string — Third street line. Only accepted for USPS international shipments, UPS domestic and UPS international shipments. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
      - `street_no` string — Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
      - `city` string, required — **required for purchase** Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state or a ZIP code (see below), if known, it will yield more accurate results. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Max 35 characters |
      - `state` string, required — **required for purchase for some countries** State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required if country requires state; Max 2 characters for US, CA, PR |
      - `zip` string, required — **required for purchase** Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 10 characters |
      - `country` string, required — ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like `US` or `DE`. If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes. Refer to this [guide](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a list of country codes. Sending a country is always required.
      - `phone` string — Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Min 1, max 15 characters | | USPS | Sender phone required for shipments during label purchase; Min 8, max 15 digits |
      - `email` string — E-mail address of the contact person, RFC3696/5321-compliant. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 80 characters | | USPS | Sender email required for shipments during label purchase |
      - `is_residential` boolean
      - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
      - `validate` boolean
  - `address_to` union, required — The recipient address, which includes the recipient's name, company name, street address, city, state, zip code, country, phone number, and email address (strings). Special characters should not be included in any address element, especially name, company, and email.
    - string — Object ID for an existing [Address](/shippoapi/public-api/addresses)
    - AddressCompleteCreateRequest — Address represents the address as retrieved from the database
      - `name` string, required — **required for purchase** First and Last Name of the addressee **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Either company or name required; No length validation (first 35 chars printed on label) |
      - `company` string — Company Name **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 35 characters; Either company or name required |
      - `street1` string, required — **required for purchase** First street line. Usually street number and street name (except for DHL Germany, see street_no). **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
      - `street2` string — Second street line. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
      - `street3` string — Third street line. Only accepted for USPS international shipments, UPS domestic and UPS international shipments. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | At least one street line required; Max 35 characters per line |
      - `street_no` string — Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany.
      - `city` string, required — **required for purchase** Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state or a ZIP code (see below), if known, it will yield more accurate results. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Max 35 characters |
      - `state` string, required — **required for purchase for some countries** State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers only accept two or three character state abbreviations. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required if country requires state; Max 2 characters for US, CA, PR |
      - `zip` string, required — **required for purchase** Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 10 characters |
      - `country` string, required — ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like `US` or `DE`. If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes. Refer to this [guide](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a list of country codes. Sending a country is always required.
      - `phone` string — Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Required; Min 1, max 15 characters | | USPS | Sender phone required for shipments during label purchase; Min 8, max 15 digits |
      - `email` string — E-mail address of the contact person, RFC3696/5321-compliant. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 80 characters | | USPS | Sender email required for shipments during label purchase |
      - `is_residential` boolean
      - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
      - `validate` boolean
  - `line_items` LineItem[], required — Array of Line Item objects
    - `currency` string — Currency of the `total_price` amount.
    - `manufacture_country` string — Country the item was manufactured in. In the Shippo dashboard, this value will be used ot pre-fill the customs declaration when creating a label for this order.
    - `max_delivery_time` string, date-time — The date and time this item needs to be delivered by, i.e. by when the carrier delivers it to the buyer. This value is used by some platforms such as eBay to measure a seller's shipping time and performance. It will be displayed in the Shippo dashboard.
    - `max_ship_time` string, date-time — The date and time this item needs to be fulfilled by, i.e. by when the shipping label needs to be created and handed over to the carrier. This value is used by some platforms such as eBay to measure a seller's handling time and performance. It will be displayed in the Shippo dashboard.
    - `quantity` integer — The quantity of this item in this order.
    - `sku` string — The stock keeping unit value of this item.
    - `title` string — Title of the line item.
    - `total_price` string — Total price paid by the buyer for this item (or these items, if quantity > 1).
    - `variant_title` string — A variant is a specific variation of an item (e.g. `size M` or `color blue`). Variants might be exposed as a separate resource in the future too. Currently the variant title is a free text field describing the variant.
    - `weight` string — Total weight of this/these item(s). Instead of specifying the weight of all items, you can also set the `total_weight` value of the order object.
    - `weight_unit` 'g' | 'kg' | 'lb' | 'oz' — The unit used for weight.
    - `object_id` string — Unique identifier of the line item object.
  - `parcel` union — Object ID for an existing User Parcel Template OR a fully formed Parcel object.
    - string — Object ID for an existing User Parcel Template
    - Parcel
      - `extra` ParcelExtra — An object holding optional extra services to be requested for each parcel in a multi-piece shipment. The following values are supported for the `extra` field of the parcel object.
        - `COD` COD — Specify collection on delivery details (UPS only).
          - `amount` string — Amount to be collected.
          - `currency` string — Currency for the amount to be collected. Currently only USD is supported for UPS.
          - `payment_method` 'SECURED_FUNDS' | 'CASH' | 'ANY' — Secured funds include money orders, certified cheques and others (see [UPS](https://www.ups.com/content/us/en/shipping/time/service/value_added/cod.html) for details). If no payment_method inputted the value defaults to "ANY".)
        - `insurance` ParcelInsurance — To add insurance to your parcel, specify `amount`, `content` and `currency`. If you do not want to add insurance to your parcel, do not set these parameters.
          - `amount` string — Declared value of the goods you want to insure.
          - `content` string — Description of parcel content.
          - `currency` string — Currency for the amount value. Currently only USD is supported for FedEx and UPS.
          - `provider` 'FEDEX' | 'UPS' | 'ONTRAC' — To have insurance cover provided by a carrier directly instead of Shippo's provider (XCover), set provider to `FEDEX`, `UPS`, or `ONTRAC`.
        - `reference_1` string — Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 40 characters (Express services); Max 30 characters (Ground services) |
        - `reference_2` string — Optional text to be printed on the shipping label if supported by carrier. Up to 50 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
      - `metadata` string
      - `mass_unit` 'g' | 'kg' | 'lb' | 'oz', required — The unit used for weight.
      - `weight` string, required — Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
      - `distance_unit` 'cm' | 'in' | 'ft' | 'm' | 'mm' | 'yd', required — The measure unit used for length, width and height.
      - `height` string, required — Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
      - `length` string, required — Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
      - `width` string, required — Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
      - `object_created` string, date-time — Date and time of Parcel creation.
      - `object_id` string — Unique identifier of the given Parcel object. This ID is required to create a Shipment object.
      - `object_owner` string — Username of the user who created the Parcel object.
      - `object_state` 'VALID' — A Parcel will only be valid when all required values have been sent and validated successfully.
      - `object_updated` string, date-time — Date and time of last Parcel update. Since you cannot update Parcels after they were created, this time stamp reflects the time when the Parcel was changed by Shippo's systems for the last time, e.g., during sorting the dimensions given.
      - `template` union — If template is passed, `length`, `width`, `height`, and `distance_unit` are not required
        - 'FedEx_Box_10kg' | 'FedEx_Box_25kg' | 'FedEx_Box_Extra_Large_1' | 'FedEx_Box_Extra_Large_2' | 'FedEx_Box_Large_1' | 'FedEx_Box_Large_2' | 'FedEx_Box_Medium_1' | 'FedEx_Box_Medium_2' | 'FedEx_Box_Small_1' | 'FedEx_Box_Small_2' | 'FedEx_Envelope' | 'FedEx_Padded_Pak' | 'FedEx_Pak_1' | 'FedEx_Pak_2' | 'FedEx_Tube' | 'FedEx_XL_Pak' — |Token | Name | Dimensions| |:---|:---|:---| | FedEx_Box_10kg | FedEx® 10kg Box | 15.81 x 12.94 x 10.19 in| | FedEx_Box_25kg | FedEx® 25kg Box | 54.80 x 42.10 x 33.50 in| | FedEx_Box_Extra_Large_1 | FedEx® Extra Large Box (X1) | 11.88 x 11.00 x 10.75 in| | FedEx_Box_Extra_Large_2 | FedEx® Extra Large Box (X2) | 15.75 x 14.13 x 6.00 in| | FedEx_Box_Large_1 | FedEx® Large Box (L1) | 17.50 x 12.38 x 3.00 in| | FedEx_Box_Large_2 | FedEx® Large Box (L2) | 11.25 x 8.75 x 7.75 in| | FedEx_Box_Medium_1 | FedEx® Medium Box (M1) | 13.25 x 11.50 x 2.38 in| | FedEx_Box_Medium_2 | FedEx® Medium Box (M2) | 11.25 x 8.75 x 4.38 in| | FedEx_Box_Small_1 | FedEx® Small Box (S1) | 12.38 x 10.88 x 1.50 in| | FedEx_Box_Small_2 | FedEx® Small Box (S2) | 11.25 x 8.75 x 2.38 in| | FedEx_Envelope | FedEx® Envelope | 12.50 x 9.50 x 0.80 in| | FedEx_Padded_Pak | FedEx® Padded Pak | 11.75 x 14.75 x 2.00 in| | FedEx_Pak_1 | FedEx® Large Pak | 15.50 x 12.00 x 0.80 in| | FedEx_Pak_2 | FedEx® Small Pak | 12.75 x 10.25 x 0.80 in| | FedEx_Tube | FedEx® Tube | 38.00 x 6.00 x 6.00 in| | FedEx_XL_Pak | FedEx® Extra Large Pak | 17.50 x 20.75 x 2.00 in|
        - 'UPS_Box_10kg' | 'UPS_Box_25kg' | 'UPS_Express_Box' | 'UPS_Express_Box_Large' | 'UPS_Express_Box_Medium' | 'UPS_Express_Box_Small' | 'UPS_Express_Envelope' | 'UPS_Express_Hard_Pak' | 'UPS_Express_Legal_Envelope' | 'UPS_Express_Pak' | 'UPS_Express_Tube' | 'UPS_Laboratory_Pak' | 'UPS_MI_BPM' | 'UPS_MI_BPM_Flat' | 'UPS_MI_BPM_Parcel' | 'UPS_MI_First_Class' | 'UPS_MI_Flat' | 'UPS_MI_Irregular' | 'UPS_MI_Machinable' | 'UPS_MI_MEDIA_MAIL' | 'UPS_MI_Parcel_Post' | 'UPS_MI_Priority' | 'UPS_MI_Standard_Flat' | 'UPS_Pad_Pak' | 'UPS_Pallet' — |Token | Name | Dimensions| |:---|:---|:---| | UPS_Box_10kg | Box 10kg | 410.00 x 335.00 x 265.00 mm| | UPS_Box_25kg | Box 25kg | 484.00 x 433.00 x 350.00 mm| | UPS_Express_Box | Express Box | 460.00 x 315.00 x 95.00 mm| | UPS_Express_Box_Large | Express Box Large | 18.00 x 13.00 x 3.00 in| | UPS_Express_Box_Medium | Express Box Medium | 15.00 x 11.00 x 3.00 in| | UPS_Express_Box_Small | Express Box Small | 13.00 x 11.00 x 2.00 in| | UPS_Express_Envelope | Express Envelope | 12.50 x 9.50 x 2.00 in| | UPS_Express_Hard_Pak | Express Hard Pak | 14.75 x 11.50 x 2.00 in| | UPS_Express_Legal_Envelope | Express Legal Envelope | 15.00 x 9.50 x 2.00 in| | UPS_Express_Pak | Express Pak | 16.00 x 12.75 x 2.00 in| | UPS_Express_Tube | Express Tube | 970.00 x 190.00 x 165.00 mm| | UPS_Laboratory_Pak | Laboratory Pak | 17.25 x 12.75 x 2.00 in| | UPS_MI_BPM | BPM (Mail Innovations - Domestic & International) | 0.00 x 0.00 x 0.00 in| | UPS_MI_BPM_Flat | BPM Flat (Mail Innovations - Domestic & International) | 0.00 x 0.00 x 0.00 in| | UPS_MI_BPM_Parcel | BPM Parcel (Mail Innovations - Domestic & International) | 0.00 x 0.00 x 0.00 in| | UPS_MI_First_Class | First Class (Mail Innovations - Domestic only) | 0.00 x 0.00 x 0.00 in| | UPS_MI_Flat | Flat (Mail Innovations - Domestic only) | 0.00 x 0.00 x 0.00 in| | UPS_MI_Irregular | Irregular (Mail Innovations - Domestic only) | 0.00 x 0.00 x 0.00 in| | UPS_MI_Machinable | Machinable (Mail Innovations - Domestic only) | 0.00 x 0.00 x 0.00 in| | UPS_MI_MEDIA_MAIL | Media Mail (Mail Innovations - Domestic only) | 0.00 x 0.00 x 0.00 in| | UPS_MI_Parcel_Post | Parcel Post (Mail Innovations - Domestic only) | 0.00 x 0.00 x 0.00 in| | UPS_MI_Priority | Priority (Mail Innovations - Domestic only) | 0.00 x 0.00 x 0.00 in| | UPS_MI_Standard_Flat | Standard Flat (Mail Innovations - Domestic only) | 0.00 x 0.00 x 0.00 in| | UPS_Pad_Pak | Pad Pak | 14.75 x 11.00 x 2.00 in| | UPS_Pallet | Pallet | 120.00 x 80.00 x 200.00 cm|
        - 'USPS_FlatRateCardboardEnvelope' | 'USPS_FlatRateEnvelope' | 'USPS_FlatRateGiftCardEnvelope' | 'USPS_FlatRateLegalEnvelope' | 'USPS_FlatRatePaddedEnvelope' | 'USPS_FlatRateWindowEnvelope' | 'USPS_IrregularParcel' | 'USPS_LargeFlatRateBoardGameBox' | 'USPS_LargeFlatRateBox' | 'USPS_APOFlatRateBox' | 'USPS_LargeVideoFlatRateBox' | 'USPS_MediumFlatRateBox1' | 'USPS_MediumFlatRateBox2' | 'USPS_RegionalRateBoxA1' | 'USPS_RegionalRateBoxA2' | 'USPS_RegionalRateBoxB1' | 'USPS_RegionalRateBoxB2' | 'USPS_SmallFlatRateBox' | 'USPS_SmallFlatRateEnvelope' | 'USPS_SoftPack' — |Token | Name | Dimensions| |:---|:---|:---| | USPS_FlatRateCardboardEnvelope | Flat Rate Cardboard Envelope | 12.50 x 9.50 x 0.75 in | | USPS_FlatRateEnvelope | Flat Rate Envelope | 12.50 x 9.50 x 0.75 in | | USPS_FlatRateGiftCardEnvelope | Flat Rate Gift Card Envelope | 10.00 x 7.00 x 0.75 in | | USPS_FlatRateLegalEnvelope | Flat Rate Legal Envelope | 15.00 x 9.50 x 0.75 in | | USPS_FlatRatePaddedEnvelope | Flat Rate Padded Envelope | 12.50 x 9.50 x 1.00 in | | USPS_FlatRateWindowEnvelope | Flat Rate Window Envelope | 10.00 x 5.00 x 0.75 in | | USPS_IrregularParcel | Irregular Parcel | 0.00 x 0.00 x 0.00 in | | USPS_LargeFlatRateBoardGameBox | Large Flat Rate Board Game Box | 24.06 x 11.88 x 3.13 in | | USPS_LargeFlatRateBox | Large Flat Rate Box | 12.25 x 12.25 x 6.00 in | | USPS_APOFlatRateBox | APO/FPO/DPO Large Flat Rate Box | 12.25 x 12.25 x 6.00 in | | USPS_LargeVideoFlatRateBox | Flat Rate Large Video Box (Int'l only) | 9.60 x 6.40 x 2.20 in | | USPS_MediumFlatRateBox1 | Medium Flat Rate Box 1 | 11.25 x 8.75 x 6.00 in | | USPS_MediumFlatRateBox2 | Medium Flat Rate Box 2 | 14.00 x 12.00 x 3.50 in | | USPS_RegionalRateBoxA1 | Regional Rate Box A1 | 10.13 x 7.13 x 5.00 in | | USPS_RegionalRateBoxA2 | Regional Rate Box A2 | 13.06 x 11.06 x 2.50 in | | USPS_RegionalRateBoxB1 | Regional Rate Box B1 | 12.25 x 10.50 x 5.50 in | | USPS_RegionalRateBoxB2 | Regional Rate Box B2 | 16.25 x 14.50 x 3.00 in | | USPS_SmallFlatRateBox | Small Flat Rate Box | 8.69 x 5.44 x 1.75 in | | USPS_SmallFlatRateEnvelope | Small Flat Rate Envelope | 10.00 x 6.00 x 4.00 in | | USPS_SoftPack | Soft Pack Padded Envelope | Length and width defined in the Parcel|
        - 'DHLeC_Irregular' | 'DHLeC_SM_Flats' — |Token | Name | Dimensions| |:---|:---|:---| | DHLeC_Irregular | Irregular Shipment | 10.00 x 10.00 x 10.00 in| | DHLeC_SM_Flats | Flats | 27.00 x 17.00 x 17.00 in|
        - 'DPD_UK_Express_Pak' — |Token | Name | Dimensions| |:---|:---|:---| | DPD_UK_Express_Pak| DPD UK Express Pak | 530.00 x 400.00 x 100.00 mm|
        - 'Fastway_Australia_Satchel_A2' | 'Fastway_Australia_Satchel_A3' | 'Fastway_Australia_Satchel_A4' | 'Fastway_Australia_Satchel_A5' — |Token | Name | Dimensions| |:---|:---|:---| | Fastway_Australia_Satchel_A2 | Satchel A2 | 594.00 x 420.00 x 48.00 mm| | Fastway_Australia_Satchel_A3 | Satchel A3 | 420.00 x 297.00 x 64.00 mm| | Fastway_Australia_Satchel_A4 | Satchel A4 | 297.00 x 210.00 x 64.00 mm| | Fastway_Australia_Satchel_A5 | Satchel A5 | 210.00 x 148.00 x 64.00 mm|
      - `test` boolean — Indicates whether the object has been created in test mode.

## Response `200`

Paginated list of live rates

- LiveRatePaginatedList
  - `next` string
  - `previous` string
  - `count` integer
  - `results` LiveRate[]
    - `amount` string — Final Rate price, expressed in the currency used in the sender's country.
    - `amount_local` string — Final Rate price, expressed in the currency used in the recipient's country.
    - `currency` string — Currency used in the sender's country, refers to `amount`. The [official ISO 4217](http://www.xe.com/iso4217.php) currency codes are used, e.g. `USD` or `EUR`.
    - `currency_local` string — Currency used in the recipient's country, refers to `amount_local`. The [official ISO 4217](http://www.xe.com/iso4217.php) currency codes are used, e.g. `USD` or "EUR".
    - `estimated_days` integer — The estimated days in transit of the rate that powers the shipping option, if available.
    - `title` string — The name of the service group being returned

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/goshippo/apis/shippo-address-api.md) · [All operations](https://skmtc.net/goshippo/apis/shippo-address-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/goshippo/shippo-address-api/versions/26fcc6af452a/schema)