---
title: "Create a new shipment"
method: POST
path: "/shipments"
tags: ["Shipments"]
---

# Create a new shipment

`POST /shipments`

Creates a new shipment object.

## Headers

- `SHIPPO-API-VERSION` string

## Request body

- ShipmentCreateRequest
  - `extra` ShipmentExtra — An object holding optional extra services to be requested.
    - `accounts_receivable_customer_account` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `alcohol` Alcohol — Indicates that a shipment contains Alcohol (Fedex and UPS only).
      - `contains_alcohol` boolean — Mandatory for Fedex and UPS. Specifies that the package contains Alcohol.
      - `recipient_type` 'licensee' | 'consumer' — Mandatory for Fedex only. License type of the recipient of the Alcohol Package.
    - `ancillary_endorsement` 'FORWARDING_SERVICE_REQUESTED' | 'RETURN_SERVICE_REQUESTED' — Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only).
    - `appropriation_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `authority_to_leave` boolean — Request `true` to give carrier permission to leave the parcel in a safe place if no one answers the door (where supported). When set to `false`, if no one is available to receive the item, the parcel will not be left (*surcharges may be applicable).
    - `bill_of_lading_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `billing` Billing — Specify billing details (UPS, FedEx, and DHL Germany only).
      - `account` string — Account number to be billed. (For DHL Germany, leave this field blank.)
      - `country` string, iso-3166 — Country iso2 code of account number to be billed (required for UPS third party billing only).
      - `participation_code` string — 2 digit code used to override your default participation code associated with your DHL Germany account.
      - `type` 'SENDER' | 'RECIPIENT' | 'THIRD_PARTY' | 'THIRD_PARTY_CONSIGNEE' | 'COLLECT' — Party to be billed. (Leave blank for DHL Germany.)
      - `zip` string — ZIP code of account number to be billed (required for UPS if there is a zip on the billing account).
    - `bypass_address_validation` boolean — Bypasses address validation (USPS, UPS, & LaserShip only).
    - `carbon_neutral` boolean — Request carbon offsets by passing true (UPS only).
    - `carrier_hub_id` string — Identifies the carrier injection site.
    - `carrier_hub_travel_time` integer — Travel time in hours from fulfillment center to carrier injection site.
    - `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".)
    - `cod_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `container_type` string — Specify container type.
    - `critical_pull_time` string — Carrier arrival time to pickup packages from the fulfillment center. UTC format: `%Y-%m-%dT%H:%M:%SZ`
    - `customer_branch` string — Specify customer branch (Lasership only).
    - `customer_reference` CustomerReference — Specify the reference field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for customer reference field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for customer reference. Up to 40 characters. If this is provided, reference_1 will be ignored. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 40 characters (Express services); Max 30 characters (Ground services) |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `dangerous_goods` DangerousGoodsObject — Container for specifying the presence of dangerous materials. This is specific to USPS, and if any contents are provided, only certain USPS service levels will be eligible. For more information, see our [guide on hazardous or dangerous materials shipping](https://docs.goshippo.com/docs/shipments/hazmat/).
      - `contains` boolean — Indicates if the shipment contains dangerous goods.
      - `biological_material` DangerousGoodsBiologicalMaterial — Container for specifying the presence of biological material.
        - `contains` boolean — Indicates if the shipment contains biological material.
      - `lithium_batteries` DangerousGoodsLithiumBatteries — Container for specifying the presence of lithium batteries.
        - `contains` boolean — Indicates if the shipment contains lithium batteries.
    - `dangerous_goods_code` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' — Dangerous Goods Code (DHL eCommerce only). See [Category Codes](https://api-legacy.dhlecs.com/docs/v2/appendix.html#dangerous-goods)
    - `dealer_order_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `delivery_instructions` string — Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only).
    - `dept_number` DepartmentNumber — Specify the department number field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for department number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for department number. Up to 40 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `dry_ice` DryIce — Specify that the package contains Dry Ice (FedEx, Veho, and UPS only).
      - `contains_dry_ice` boolean — Mandatory. Specifies that the package contains Dry Ice.
      - `weight` string — Mandatory. Units must be in Kilograms. Cannot be greater than package weight.
    - `fda_product_code` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `fulfillment_center` string — The fulfilment center where the package originates from.
    - `insurance` Insurance — To add 3rd party insurance powered by [XCover](https://docs.goshippo.com/docs/shipments/shippinginsurance/), specify `amount`, `content`, and `currency`. Alternatively, you can choose carrier provided insurance by additionally specifying `provider` (UPS, FedEx and OnTrac only). If you do not want to add insurance to your shipment, do not set these parameters.
      - `amount` string — Declared value of the goods you want to insure.
      - `content` string — Description of package content.
      - `currency` string, iso-4217 — 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`.
    - `invoice_number` InvoiceNumber — Specify the invoice number field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for invoice number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for invoice number. Up to 40 characters. If provided, this will be used on the label instead of shipment.customs_declaration.invoice. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `is_return` boolean — This field specifies if it is a scan-based return shipment. See the [Create a return shipment](https://docs.goshippo.com/docs/shipments/returns/) section for more details.
    - `lasership_attrs` ShipmentExtraLasershipAttributesEnum[] — Specify Lasership Attributes (Lasership only). Multiple options accepted.
    - `lasership_declared_value` string — Declared value (Lasership only). Defaults to `50.00`.
    - `manifest_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `model_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `part_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `po_number` PoNumber — Specify the PO number field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for PO number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for PO number. Up to 40 characters. If this is provided, reference_2 will be ignored. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `preferred_delivery_timeframe` '10001200' | '12001400' | '14001600' | '16001800' | '18002000' | '19002100' — Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is `HHMMHHMM`
    - `premium` boolean — Add premium service to a shipment (DHL Germany international shipments only).
    - `production_code` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `purchase_request_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `qr_code_requested` boolean — Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only).
    - `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. For DHL eCommerce, this field can be used for billing reference. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
    - `request_retail_rates` boolean — Returns retail rates instead of account-based rates (UPS and FedEx only).
    - `return_service_type` union — Request additional return option for return shipments (UPS and Lasership only).
      - 'PRINT_AND_MAIL' | 'ATTEMPT_1' | 'ATTEMPT_3' | 'ELECTRONIC_LABEL'
      - 'NO_RETURN'
    - `rma_number` RmaNumber — Specify the RMA number field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for RMA number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for RMA number. Up to 40 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 20 characters |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `saturday_delivery` boolean — Marks shipment as to be delivered on a Saturday.
    - `salesperson_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `serial_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `signature_confirmation` 'STANDARD' | 'ADULT' | 'CERTIFIED' | 'INDIRECT' | 'CARRIER_CONFIRMATION' — Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only) or Indirect signature (FedEx only) or Carrier Confirmation (Deutsche Post only).
    - `store_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `transaction_reference_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `usmca_eligible` boolean — UPS only. Request USMCA (United States-Mexico-Canada Agreement) preferential tariff treatment. When enabled, it includes the USMCA eligibility declaration in customs documentation. Supported routes and value limits: - USA/Canada → Mexico: ≤ $1,000 USD - Canada/Mexico → USA: ≤ $2,500 USD - USA/Mexico → Canada: ≤ $3,300 CAD Only for declaration-only shipments, full USMCA - FormType 04 (Certificate of Origin) is not supported.
  - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
  - `shipment_date` string — Date the shipment will be tendered to the carrier. Must be in the format `2014-01-18T00:35:03.463Z`. Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.
  - `address_from` union, required
    - AddressCreateRequest — Address represents the address as retrieved from the database
      - `name` string — **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 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 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 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 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 — Set to true to validate Address object.
    - string — [Address](/shippoapi/public-api/addresses) `object_id` of a previously created address.
  - `address_return` union
    - AddressCreateRequest — Address represents the address as retrieved from the database
      - `name` string — **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 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 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 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 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 — Set to true to validate Address object.
    - string — [Address](/shippoapi/public-api/addresses) `object_id` of a previously created address.
  - `address_to` union, required
    - AddressCreateRequest — Address represents the address as retrieved from the database
      - `name` string — **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 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 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 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 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 — Set to true to validate Address object.
    - string — [Address](/shippoapi/public-api/addresses) `object_id` of a previously created address.
  - `customs_declaration` union
    - CustomsDeclarationCreateRequest
      - `aes_itn` string — **required if eel_pfc is `AES_ITN`** AES / ITN reference of the shipment.
      - `b13a_filing_option` 'FILED_ELECTRONICALLY' | 'SUMMARY_REPORTING' | 'NOT_REQUIRED' — B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). [More information on reporting commercial exports from Canada.](https://www.cbsa-asfc.gc.ca/services/export/guide-eng.html) Allowed values available [here](/shippoapi/public-api/customs-declaration-b13a-filing-option)
      - `b13a_number` string — **must be provided if and only if b13a_filing_option is provided** Represents the Proof of Report (POR) Number when b13a_filing_option is `FILED_ELECTRONICALLY`; the Summary ID Number when b13a_filing_option is `SUMMARY_REPORTING`; or the Exemption Number when b13a_filing_option is `NOT_REQUIRED`.
      - `certificate` string — Certificate reference of the shipment.
      - `certify` boolean, required — Expresses that the certify_signer has provided all information of this customs declaration truthfully.
      - `certify_signer` string, required — Name of the person who created the customs declaration and is responsible for the validity of all information provided.
      - `commercial_invoice` boolean
      - `contents_explanation` string — **required if contents_type is `OTHER`** Explanation of the type of goods of the shipment.
      - `disclaimer` string — Disclaimer for the shipment and customs information that have been provided. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 554 characters |
      - `duties_payor` object — Specifies who will pay the duties for the shipment. Only accepted for FedEx shipments.
        - `account` string — Account number to be billed for duties.
        - `type` 'SENDER' | 'RECIPIENT' | 'THIRD_PARTY' — Party to be billed for duties.
        - `address` object
          - `name` string — Name of the party to be billed for duties.
          - `zip` string — Postal code of the party to be billed for duties.
          - `country` string — Country ISO code of account number to be billed.
      - `exporter_identification` CustomsExporterIdentification — Additional exporter identification that may be required to ship in certain countries
        - `eori_number` string — Economic Operators' Registration and Identification (EORI) number. Must start with a 2 character country code followed by a 6-17 character alphanumeric identifier (e.g. PL1234567890ABCDE). [More information on EORI.](https://ec.europa.eu/taxation_customs/business/customs-procedures/general-overview/economic-operators-registration-identification-number-eori_en)
        - `tax_id` CustomsTaxIdentification — Tax identification that may be required to ship in certain countries. Typically used to assess duties on goods that are crossing a border.
          - `number` string — Tax identification number.
          - `type` 'EIN' | 'VAT' | 'IOSS' | 'ARN' — Type of tax identification. * `EIN` - Employer Identification Number, also known as a Federal Tax Identification Number. * `VAT` - Value Added Tax identification number. * `IOSS` - Import One-Stop Shop * `ARN` - Australian Taxation Office Reference Number
      - `exporter_reference` string — Exporter reference of an export shipment.
      - `importer_reference` string — Importer reference of an import shipment.
      - `is_vat_collected` boolean — Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.
      - `invoice` string — Invoice reference of the shipment.
      - `license` string — License reference of the shipment.
      - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
      - `notes` string — Additional notes to be included in the customs declaration.
      - `address_importer` AddressImporter — Object that represents the address of the importer
        - `name` string — First and Last Name of the addressee
        - `company` string — Company Name
        - `street1` string — First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no).
        - `street2` string — Second street line, 35 character limit.
        - `street3` string — Third street line, 35 character limit. Only accepted for USPS international shipments, UPS domestic and UPS international shipments.
        - `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 — Name of a city
        - `state` string — **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.
        - `zip` string — Postal code of an Address.
        - `country` string — Example: `US` or `DE`. All accepted values can be found on the [Official ISO Website](http://www.iso.org/). 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.
        - `email` string — E-mail address of the contact person, RFC3696/5321-compliant.
        - `is_residential` boolean — Indicates whether the address provided is a residential address or not.
      - `contents_type` 'DOCUMENTS' | 'GIFT' | 'SAMPLE' | 'MERCHANDISE' | 'HUMANITARIAN_DONATION' | 'RETURN_MERCHANDISE' | 'OTHER', required — Type of goods of the shipment. Allowed values available [here](/shippoapi/public-api/customs-declaration-contents-type)
      - `eel_pfc` 'NOEEI_30_37_a' | 'NOEEI_30_37_h' | 'NOEEI_30_37_f' | 'NOEEI_30_36' | 'AES_ITN' — EEL / PFC type of the shipment. For most shipments from the US to CA, `NOEEI_30_36` is applicable; for most other shipments from the US, `NOEEI_30_37_a` is applicable. Allowed values available [here](/shippoapi/public-api/customs-declaration-eelpfc)
      - `incoterm` 'DDP' | 'DDU' | 'FCA' | 'DAP' | 'eDAP' — The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express, FedEx, and DPD UK. If expecting DAP for other carriers, please use DDU. Allowed values available [here](/shippoapi/public-api/customs-declaration-incoterm) Carrier-specific restrictions are in the table below. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Must be one of DDP, DDU, FCA, DAP |
      - `items` CustomsItemCreateRequest[], required
        - `description` string, required — Text description of your item.
        - `eccn_ear99` string — Export Control Classification Number, required on some exports from the United States.
        - `mass_unit` 'g' | 'kg' | 'lb' | 'oz', required — The unit used for weight.
        - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
        - `net_weight` string, required — Total weight of this item, i.e. quantity * weight per item.
        - `origin_country` string, required — Country of origin of the item. Example: `US` or `DE`. All accepted values can be found on the [Official ISO Website](http://www.iso.org/).
        - `quantity` integer, required — Quantity of this item in the shipment you send. Must be greater than 0.
        - `sku_code` string — SKU code of the item, which is required by some carriers.
        - `hs_code` string — HS code of the item, which is required by some carriers. If `tariff_number` is not provided, `hs_code` will be used. If both `hs_code` and `tariff_number` are provided, `tariff_number` will be used. 50 character limit.
        - `tariff_number` string — The tariff number of the item. If `tariff_number` is not provided, `hs_code` will be used. If both `hs_code` and `tariff_number` are provided, `tariff_number` will be used. 12 character limit.
        - `value_amount` string, required — Total value of this item, i.e. quantity * value per item.
        - `value_currency` string, required — Currency used for value_amount. The [official ISO 4217](http://www.xe.com/iso4217.php) currency codes are used, e.g. `USD` or `EUR`.
      - `non_delivery_option` 'ABANDON' | 'RETURN', required — Indicates how the carrier should proceed in case the shipment can't be delivered. Allowed values available [here](/shippoapi/public-api/customs-declaration-non-delivery-option)
      - `test` boolean
    - string — [Customs Declaration](/shippoapi/public-api/customs-declarations) `object_id` of a previously created customs declaration.
  - `async` boolean
  - `carrier_accounts` string[] — List of [Carrier Accounts](/shippoapi/public-api/carrier-accounts) `object_id`s used to filter the returned rates. If set, only rates from these carriers will be returned.
  - `parcels` union[], required — List of parcels to be shipped. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 items |
    - union
      - ParcelCreateRequest
        - `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.
      - ParcelCreateFromTemplateRequest
        - `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.
        - `template` union, required — 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|
      - string — [Parcel](/shippoapi/public-api/parcels) `object_id` of a previously created parcel.

## Response `201`

Shipment

- Shipment — Shipment represents the parcel as retrieved from the database
  - `extra` ShipmentExtra — An object holding optional extra services to be requested.
    - `accounts_receivable_customer_account` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `alcohol` Alcohol — Indicates that a shipment contains Alcohol (Fedex and UPS only).
      - `contains_alcohol` boolean — Mandatory for Fedex and UPS. Specifies that the package contains Alcohol.
      - `recipient_type` 'licensee' | 'consumer' — Mandatory for Fedex only. License type of the recipient of the Alcohol Package.
    - `ancillary_endorsement` 'FORWARDING_SERVICE_REQUESTED' | 'RETURN_SERVICE_REQUESTED' — Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only).
    - `appropriation_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `authority_to_leave` boolean — Request `true` to give carrier permission to leave the parcel in a safe place if no one answers the door (where supported). When set to `false`, if no one is available to receive the item, the parcel will not be left (*surcharges may be applicable).
    - `bill_of_lading_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `billing` Billing — Specify billing details (UPS, FedEx, and DHL Germany only).
      - `account` string — Account number to be billed. (For DHL Germany, leave this field blank.)
      - `country` string, iso-3166 — Country iso2 code of account number to be billed (required for UPS third party billing only).
      - `participation_code` string — 2 digit code used to override your default participation code associated with your DHL Germany account.
      - `type` 'SENDER' | 'RECIPIENT' | 'THIRD_PARTY' | 'THIRD_PARTY_CONSIGNEE' | 'COLLECT' — Party to be billed. (Leave blank for DHL Germany.)
      - `zip` string — ZIP code of account number to be billed (required for UPS if there is a zip on the billing account).
    - `bypass_address_validation` boolean — Bypasses address validation (USPS, UPS, & LaserShip only).
    - `carbon_neutral` boolean — Request carbon offsets by passing true (UPS only).
    - `carrier_hub_id` string — Identifies the carrier injection site.
    - `carrier_hub_travel_time` integer — Travel time in hours from fulfillment center to carrier injection site.
    - `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".)
    - `cod_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `container_type` string — Specify container type.
    - `critical_pull_time` string — Carrier arrival time to pickup packages from the fulfillment center. UTC format: `%Y-%m-%dT%H:%M:%SZ`
    - `customer_branch` string — Specify customer branch (Lasership only).
    - `customer_reference` CustomerReference — Specify the reference field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for customer reference field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for customer reference. Up to 40 characters. If this is provided, reference_1 will be ignored. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 40 characters (Express services); Max 30 characters (Ground services) |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `dangerous_goods` DangerousGoodsObject — Container for specifying the presence of dangerous materials. This is specific to USPS, and if any contents are provided, only certain USPS service levels will be eligible. For more information, see our [guide on hazardous or dangerous materials shipping](https://docs.goshippo.com/docs/shipments/hazmat/).
      - `contains` boolean — Indicates if the shipment contains dangerous goods.
      - `biological_material` DangerousGoodsBiologicalMaterial — Container for specifying the presence of biological material.
        - `contains` boolean — Indicates if the shipment contains biological material.
      - `lithium_batteries` DangerousGoodsLithiumBatteries — Container for specifying the presence of lithium batteries.
        - `contains` boolean — Indicates if the shipment contains lithium batteries.
    - `dangerous_goods_code` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' — Dangerous Goods Code (DHL eCommerce only). See [Category Codes](https://api-legacy.dhlecs.com/docs/v2/appendix.html#dangerous-goods)
    - `dealer_order_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `delivery_instructions` string — Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only).
    - `dept_number` DepartmentNumber — Specify the department number field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for department number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for department number. Up to 40 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `dry_ice` DryIce — Specify that the package contains Dry Ice (FedEx, Veho, and UPS only).
      - `contains_dry_ice` boolean — Mandatory. Specifies that the package contains Dry Ice.
      - `weight` string — Mandatory. Units must be in Kilograms. Cannot be greater than package weight.
    - `fda_product_code` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `fulfillment_center` string — The fulfilment center where the package originates from.
    - `insurance` Insurance — To add 3rd party insurance powered by [XCover](https://docs.goshippo.com/docs/shipments/shippinginsurance/), specify `amount`, `content`, and `currency`. Alternatively, you can choose carrier provided insurance by additionally specifying `provider` (UPS, FedEx and OnTrac only). If you do not want to add insurance to your shipment, do not set these parameters.
      - `amount` string — Declared value of the goods you want to insure.
      - `content` string — Description of package content.
      - `currency` string, iso-4217 — 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`.
    - `invoice_number` InvoiceNumber — Specify the invoice number field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for invoice number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for invoice number. Up to 40 characters. If provided, this will be used on the label instead of shipment.customs_declaration.invoice. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `is_return` boolean — This field specifies if it is a scan-based return shipment. See the [Create a return shipment](https://docs.goshippo.com/docs/shipments/returns/) section for more details.
    - `lasership_attrs` ShipmentExtraLasershipAttributesEnum[] — Specify Lasership Attributes (Lasership only). Multiple options accepted.
    - `lasership_declared_value` string — Declared value (Lasership only). Defaults to `50.00`.
    - `manifest_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `model_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `part_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `po_number` PoNumber — Specify the PO number field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for PO number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for PO number. Up to 40 characters. If this is provided, reference_2 will be ignored. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `preferred_delivery_timeframe` '10001200' | '12001400' | '14001600' | '16001800' | '18002000' | '19002100' — Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is `HHMMHHMM`
    - `premium` boolean — Add premium service to a shipment (DHL Germany international shipments only).
    - `production_code` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `purchase_request_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `qr_code_requested` boolean — Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only).
    - `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. For DHL eCommerce, this field can be used for billing reference. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 30 characters |
    - `request_retail_rates` boolean — Returns retail rates instead of account-based rates (UPS and FedEx only).
    - `return_service_type` union — Request additional return option for return shipments (UPS and Lasership only).
      - 'PRINT_AND_MAIL' | 'ATTEMPT_1' | 'ATTEMPT_3' | 'ELECTRONIC_LABEL'
      - 'NO_RETURN'
    - `rma_number` RmaNumber — Specify the RMA number field on the label (FedEx and UPS only).
      - `prefix` string — Custom prefix for RMA number field (ZPL labels only). Up to 11 characters, including trailing spaces. Empty string indicates removal of default prefix. To use the default prefix, do not include this property.
      - `value` string — Optional text to be printed on the shipping label for RMA number. Up to 40 characters. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 20 characters |
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `saturday_delivery` boolean — Marks shipment as to be delivered on a Saturday.
    - `salesperson_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `serial_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `signature_confirmation` 'STANDARD' | 'ADULT' | 'CERTIFIED' | 'INDIRECT' | 'CARRIER_CONFIRMATION' — Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only) or Indirect signature (FedEx only) or Carrier Confirmation (Deutsche Post only).
    - `store_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `transaction_reference_number` UPSReferenceFields
      - `prefix` string — Custom prefix text.
      - `value` string — Label reference text. 35 character limit.
      - `ref_sort` integer — Order UPS reference fields are printed on ZPL labels. For UPS shipments, if you choose to set `ref_sort` for one reference, you must set `ref_sort` for all other supported UPS references using unique integers.
    - `usmca_eligible` boolean — UPS only. Request USMCA (United States-Mexico-Canada Agreement) preferential tariff treatment. When enabled, it includes the USMCA eligibility declaration in customs documentation. Supported routes and value limits: - USA/Canada → Mexico: ≤ $1,000 USD - Canada/Mexico → USA: ≤ $2,500 USD - USA/Mexico → Canada: ≤ $3,300 CAD Only for declaration-only shipments, full USMCA - FormType 04 (Certificate of Origin) is not supported.
  - `metadata` string, required — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
  - `shipment_date` string — Date the shipment will be tendered to the carrier. Must be in the format `2014-01-18T00:35:03.463Z`. Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.
  - `address_from` AddressFrom, required — Address represents the address as retrieved from the database
    - `name` string — **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 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 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 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 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.
    - `is_complete` boolean — Complete addresses contain all required values. Incomplete addresses have failed one or multiple validations. Incomplete Addresses are eligible for requesting rates but lack at least one required value for purchasing labels.
    - `latitude` union — Latitude of address
      - number
      - string
    - `longitude` union — Longitude of address
      - number
      - string
    - `object_created` string, date-time — Date and time of Address creation.
    - `object_id` string — Unique identifier of the given Address object. This ID is required to create a Shipment object.
    - `object_owner` string — Username of the user who created the Address object.
    - `object_updated` string, date-time — Date and time of last Address update. Since you cannot update Addresses after they were created, this time stamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the approximation of one or more values.
    - `validation_results` AddressValidationResults — Object that contains information regarding if an address had been validated or not. Also contains any messages generated during validation. Children keys are `is_valid`(boolean) and `messages`(array).
      - `is_valid` boolean
      - `messages` AddressValidationResultsMessage[]
        - `code` string — See [Address Validation Codes](/shippoapi/public-api/address-validation-codes)
        - `source` string — See [Address Validation Source](/shippoapi/public-api/address-validation-source)
        - `text` string
        - `type` string
    - `test` boolean — Indicates whether the object has been created in test mode.
  - `address_return` AddressReturn — Address represents the address as retrieved from the database
    - `name` string — **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 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 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 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 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.
    - `is_complete` boolean — Complete addresses contain all required values. Incomplete addresses have failed one or multiple validations. Incomplete Addresses are eligible for requesting rates but lack at least one required value for purchasing labels.
    - `latitude` union — Latitude of address
      - number
      - string
    - `longitude` union — Longitude of address
      - number
      - string
    - `object_created` string, date-time — Date and time of Address creation.
    - `object_id` string — Unique identifier of the given Address object. This ID is required to create a Shipment object.
    - `object_owner` string — Username of the user who created the Address object.
    - `object_updated` string, date-time — Date and time of last Address update. Since you cannot update Addresses after they were created, this time stamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the approximation of one or more values.
    - `validation_results` AddressValidationResults — Object that contains information regarding if an address had been validated or not. Also contains any messages generated during validation. Children keys are `is_valid`(boolean) and `messages`(array).
      - `is_valid` boolean
      - `messages` AddressValidationResultsMessage[]
        - `code` string — See [Address Validation Codes](/shippoapi/public-api/address-validation-codes)
        - `source` string — See [Address Validation Source](/shippoapi/public-api/address-validation-source)
        - `text` string
        - `type` string
    - `test` boolean — Indicates whether the object has been created in test mode.
  - `address_to` AddressTo, required — Address represents the address as retrieved from the database
    - `name` string — **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 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 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 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 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.
    - `is_complete` boolean — Complete addresses contain all required values. Incomplete addresses have failed one or multiple validations. Incomplete Addresses are eligible for requesting rates but lack at least one required value for purchasing labels.
    - `latitude` union — Latitude of address
      - number
      - string
    - `longitude` union — Longitude of address
      - number
      - string
    - `object_created` string, date-time — Date and time of Address creation.
    - `object_id` string — Unique identifier of the given Address object. This ID is required to create a Shipment object.
    - `object_owner` string — Username of the user who created the Address object.
    - `object_updated` string, date-time — Date and time of last Address update. Since you cannot update Addresses after they were created, this time stamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the approximation of one or more values.
    - `validation_results` AddressValidationResults — Object that contains information regarding if an address had been validated or not. Also contains any messages generated during validation. Children keys are `is_valid`(boolean) and `messages`(array).
      - `is_valid` boolean
      - `messages` AddressValidationResultsMessage[]
        - `code` string — See [Address Validation Codes](/shippoapi/public-api/address-validation-codes)
        - `source` string — See [Address Validation Source](/shippoapi/public-api/address-validation-source)
        - `text` string
        - `type` string
    - `test` boolean — Indicates whether the object has been created in test mode.
  - `carrier_accounts` string[], required — An array of object_ids of the carrier account objects to be used for getting shipping rates for this shipment. If no carrier account object_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the `active` field set.
  - `customs_declaration` CustomsDeclaration
    - `aes_itn` string — **required if eel_pfc is `AES_ITN`** AES / ITN reference of the shipment.
    - `b13a_filing_option` string — B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). [More information on reporting commercial exports from Canada.](https://www.cbsa-asfc.gc.ca/services/export/guide-eng.html) Allowed values available [here](/shippoapi/public-api/customs-declaration-b13a-filing-option)
    - `b13a_number` string — **must be provided if and only if b13a_filing_option is provided** Represents the Proof of Report (POR) Number when b13a_filing_option is `FILED_ELECTRONICALLY`; the Summary ID Number when b13a_filing_option is `SUMMARY_REPORTING`; or the Exemption Number when b13a_filing_option is `NOT_REQUIRED`.
    - `certificate` string — Certificate reference of the shipment.
    - `certify` boolean, required — Expresses that the certify_signer has provided all information of this customs declaration truthfully.
    - `certify_signer` string, required — Name of the person who created the customs declaration and is responsible for the validity of all information provided.
    - `commercial_invoice` boolean
    - `contents_explanation` string — **required if contents_type is `OTHER`** Explanation of the type of goods of the shipment.
    - `disclaimer` string — Disclaimer for the shipment and customs information that have been provided. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Max 554 characters |
    - `duties_payor` object — Specifies who will pay the duties for the shipment. Only accepted for FedEx shipments.
      - `account` string — Account number to be billed for duties.
      - `type` 'SENDER' | 'RECIPIENT' | 'THIRD_PARTY' — Party to be billed for duties.
      - `address` object
        - `name` string — Name of the party to be billed for duties.
        - `zip` string — Postal code of the party to be billed for duties.
        - `country` string — Country ISO code of account number to be billed.
    - `exporter_identification` CustomsExporterIdentification — Additional exporter identification that may be required to ship in certain countries
      - `eori_number` string — Economic Operators' Registration and Identification (EORI) number. Must start with a 2 character country code followed by a 6-17 character alphanumeric identifier (e.g. PL1234567890ABCDE). [More information on EORI.](https://ec.europa.eu/taxation_customs/business/customs-procedures/general-overview/economic-operators-registration-identification-number-eori_en)
      - `tax_id` CustomsTaxIdentification — Tax identification that may be required to ship in certain countries. Typically used to assess duties on goods that are crossing a border.
        - `number` string — Tax identification number.
        - `type` 'EIN' | 'VAT' | 'IOSS' | 'ARN' — Type of tax identification. * `EIN` - Employer Identification Number, also known as a Federal Tax Identification Number. * `VAT` - Value Added Tax identification number. * `IOSS` - Import One-Stop Shop * `ARN` - Australian Taxation Office Reference Number
    - `exporter_reference` string — Exporter reference of an export shipment.
    - `importer_reference` string — Importer reference of an import shipment.
    - `is_vat_collected` boolean — Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.
    - `invoice` string — Invoice reference of the shipment.
    - `license` string — License reference of the shipment.
    - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
    - `notes` string — Additional notes to be included in the customs declaration.
    - `address_importer` string — Object ID of the Importer address.
    - `contents_type` string, required — Type of goods of the shipment. Allowed values available [here](/shippoapi/public-api/customs-declaration-contents-type)
    - `eel_pfc` string — EEL / PFC type of the shipment. For most shipments from the US to CA, `NOEEI_30_36` is applicable; for most other shipments from the US, `NOEEI_30_37_a` is applicable. Allowed values available [here](/shippoapi/public-api/customs-declaration-eelpfc)
    - `incoterm` string — The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express, FedEx, and DPD UK. If expecting DAP for other carriers, please use DDU. Allowed values available [here](/shippoapi/public-api/customs-declaration-incoterm) Carrier-specific restrictions are in the table below. **Carrier-Specific Constraints:** | Carrier | Constraints | |:---|:---| | FedEx | Must be one of DDP, DDU, FCA, DAP |
    - `invoiced_charges` CustomsInvoicedCharges — Additional invoiced charges to be shown on the Customs Declaration Commercial Invoice.
      - `currency` string, iso-4217, required — Currency for the invoiced charges amounts incurred on the end consumer.
      - `total_shipping` string — Total shipping paid by the buyer.
      - `total_taxes` string — Total taxes paid by the buyer.
      - `total_duties` string — Total duties paid by the buyer.
      - `other_fees` string — Other fees paid by the buyer.
    - `items` string[], required — Distinct Parcel content items as Customs Items object_ids.
    - `non_delivery_option` string, required — Indicates how the carrier should proceed in case the shipment can't be delivered. Allowed values available [here](/shippoapi/public-api/customs-declaration-non-delivery-option)
    - `object_created` string, date-time — Date and time of object creation.
    - `object_id` string — Unique identifier of the given object.
    - `object_owner` string — Username of the user who created the object.
    - `object_state` 'VALID' | 'INVALID' — Indicates the validity of the enclosing object
    - `object_updated` string, date-time — Date and time of last object update.
    - `test` boolean — Indicates whether the object has been created in test mode.
  - `messages` ResponseMessage[], required
    - `source` string — Origin of message
    - `code` string — Classification of message
    - `text` string — Message content
  - `object_created` string, date-time, required — Date and time of Shipment creation.
  - `object_id` string, required — Unique identifier of the given Shipment object.
  - `object_owner` string, required — Username of the user who created the Shipment object.
  - `object_updated` string, date-time, required — Date and time of last Shipment update.
  - `parcels` Parcel[], required — List of Parcel objects to be shipped.
    - `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.
  - `rates` Rate[], required — An array with all available rates. If `async` has been set to `false` in the request, this will be populated with all available rates in the response. Otherwise rates will be created asynchronously and this array will initially be empty.
    - `amount` string, required — Final Rate price, expressed in the currency used in the sender's country.
    - `amount_local` string, required — Final Rate price, expressed in the currency used in the recipient's country.
    - `currency` string, required — 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, required — 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".
    - `arrives_by` string — Predicted time the carrier will deliver the package in the destination's local time zone. In the format `HH:MM:SS`.
    - `attributes` string[], required — An array containing specific attributes of this Rate in context of the entire shipment. Attributes can be assigned `CHEAPEST`, `FASTEST`, or `BESTVALUE`.
    - `carrier_account` string, required — Object ID of the carrier account that has been used to retrieve the rate.
    - `duration_terms` string — Further clarification of the transit times. Often, this includes notes that the transit time as given in "days" is only an average, not a guaranteed time.
    - `estimated_days` integer — Estimated transit time (duration) in days of the Parcel at the given servicelevel. Please note that this is not binding, but only an average value as given by the provider. Shippo is not able to guarantee any transit times.
    - `included_insurance_price` string — Cost to the user to insure the Rate for the requested amount of coverage, if insurance coverage was requested. Expressed in the currency used in the sender's country. Will be null if no insurance coverage was requested, or if insurance is requested from a non-standard insurance provider. Please note this price is already included in the `amount` and `amount_local` fields on the Rate. Do not add this field to them.
    - `messages` ResponseMessage[]
      - `source` string — Origin of message
      - `code` string — Classification of message
      - `text` string — Message content
    - `object_created` string, date-time, required — Date and time of Rate creation.
    - `object_id` string, required — Unique identifier of the given Rate object.
    - `object_owner` string, required — Username of the user who created the rate object.
    - `provider` string, required — Carrier offering the rate, e.g., `FedEx` or `Deutsche Post DHL`.
    - `provider_image_75` string — URL to the provider logo with max. dimensions of 75*75px. Please refer to the provider's Logo Usage Guidelines before using the logo.
    - `provider_image_200` string — URL to the provider logo with max. dimensions of 200*200px. Please refer to the provider's Logo Usage Guidelines before using the logo.
    - `servicelevel` ServiceLevelWithParent, required — Contains details regarding the service level for the given rate.
      - `name` string — Name of the Rate's servicelevel, e.g. `International Priority` or `Standard Post`. A servicelevel commonly defines the transit time of a Shipment (e.g., Express vs. Standard), along with other properties. These names vary depending on the provider.
      - `terms` string — Further clarification of the service. For FedEx, a value of `ONERATE` indicates this rate is a FedEx One Rate variant of the same service level — it shares the same `token` as the standard-rate object but is a separate rate with its own `amount`. Standard (non-One Rate) rates have an empty string here.
      - `token` string — Token of the Rate's servicelevel, e.g. `usps_priority` or `fedex_ground`. See [servicelevels](/shippoapi/public-api/service-levels).
      - `extended_token` string — Unique, extended version of the Service Level "token". Guaranteed to be unique across all Service Levels, and may help offer insight into the specific Service Level it describes.
      - `parent_servicelevel` object — Used for some Service Levels to link to the more "generic" version of this Service Level - for example, if this Service Level is a variation specific to shipments to Europe("ups_saver_eu"), the "parent" is the fully generic version ("ups_saver"). Helpful when displaying Service Levels to users. Has the same structure of the servicelevel - "name", "token", "terms", and "extended_token", or it is otherwise null.
        - `name` string — Name of the Rate's servicelevel, e.g. `International Priority` or `Standard Post`. A servicelevel commonly defines the transit time of a Shipment (e.g., Express vs. Standard), along with other properties. These names vary depending on the provider.
        - `terms` string — Further clarification of the service. For FedEx, a value of `ONERATE` indicates this rate is a FedEx One Rate variant of the same service level — it shares the same `token` as the standard-rate object but is a separate rate with its own `amount`. Standard (non-One Rate) rates have an empty string here.
        - `token` string — Token of the Rate's servicelevel, e.g. `usps_priority` or `fedex_ground`. See [servicelevels](/shippoapi/public-api/service-levels).
        - `extended_token` string — Unique, extended version of the Service Level "token". Guaranteed to be unique across all Service Levels, and may help offer insight into the specific Service Level it describes.
    - `shipment` string, required
    - `test` boolean — Indicates whether the object has been created in test mode.
    - `zone` string — The parcel's transit zone token. These tokens can vary depending on the provider.
  - `status` 'ERROR' | 'QUEUED' | 'SUCCESS' | 'WAITING', required — `Waiting` shipments have been successfully submitted but not yet been processed. `Queued` shipments are currently being processed. `Success` shipments have been processed successfully, meaning that rate generation has concluded. `Error` does not occur currently and is reserved for future use.
  - `test` boolean — Indicates whether the object has been created in test mode.

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/goshippo/apis/shippo-external-api.md) · [All operations](https://skmtc.net/goshippo/apis/shippo-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/goshippo/shippo-external-api/revisions/13280a44853c/schema)