# Create a new shipment

Creates a new shipment object.

Endpoint: POST /shipments
Version: 2018-02-08
Security: APIKeyHeader

## Header parameters:

  - `SHIPPO-API-VERSION` (string)
    Optional string used to pick a non-default API version to use. See our API version guide.
    Example: "2018-02-08"

## Request fields (application/json):

  - `extra` (object)
    An object holding optional extra services to be requested.

  - `extra.accounts_receivable_customer_account` (object)
    UPS only. Adds custom accounts receivable customer account reference to UPS labels.

  - `extra.accounts_receivable_customer_account.prefix` (string)
    Custom prefix text.
    Example: "ABC"

  - `extra.accounts_receivable_customer_account.value` (string)
    Label reference text. 35 character limit.
    Example: "value"

  - `extra.accounts_receivable_customer_account.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.
    Example: 1

  - `extra.alcohol` (object)
    Indicates that a shipment contains Alcohol (Fedex and UPS only).

  - `extra.alcohol.contains_alcohol` (boolean)
    Mandatory for Fedex and UPS. Specifies that the package contains Alcohol.

  - `extra.alcohol.recipient_type` (any)
    Mandatory for Fedex only. License type of the recipient of the Alcohol Package.
    Enum: "licensee", "consumer"

  - `extra.ancillary_endorsement` (any)
    Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only).
    Enum: "FORWARDING_SERVICE_REQUESTED", "RETURN_SERVICE_REQUESTED"

  - `extra.appropriation_number` (object)
    UPS only. Adds custom appropriation number reference to UPS labels.

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

  - `extra.bill_of_lading_number` (object)
    UPS only. Adds custom bill of lading number reference to UPS labels.

  - `extra.billing` (object)
    Specify billing details (UPS, FedEx, and DHL Germany only).

  - `extra.billing.account` (string)
    Account number to be billed. (For DHL Germany, leave this field blank.)

  - `extra.billing.country` (string)
    Country iso2 code of account number to be billed (required for UPS third party billing only).

  - `extra.billing.participation_code` (string)
    2 digit code used to override your default participation code associated with your DHL Germany account.

  - `extra.billing.type` (any)
    Party to be billed. (Leave blank for DHL Germany.)
    Enum: "SENDER", "RECIPIENT", "THIRD_PARTY", "THIRD_PARTY_CONSIGNEE", "COLLECT"

  - `extra.billing.zip` (string)
    ZIP code of account number to be billed (required for UPS if there is a zip on the billing account).

  - `extra.bypass_address_validation` (boolean)
    Bypasses address validation (USPS, UPS, & LaserShip only).

  - `extra.carbon_neutral` (boolean)
    Request carbon offsets by passing true (UPS only).

  - `extra.carrier_hub_id` (string)
    Identifies the carrier injection site.

  - `extra.carrier_hub_travel_time` (integer)
    Travel time in hours from fulfillment center to carrier injection site.

  - `extra.COD` (object)
    Specify collection on delivery details (UPS only).

  - `extra.COD.amount` (string)
    Amount to be collected.
    Example: "5.5"

  - `extra.COD.currency` (string)
    Currency for the amount to be collected. Currently only USD is supported for UPS.
    Example: "USD"

  - `extra.COD.payment_method` (string)
    Secured funds include money orders, certified cheques and others (see 
UPS for details). 
If no payment_method inputted the value defaults to "ANY".)
    Enum: "SECURED_FUNDS", "CASH", "ANY"

  - `extra.cod_number` (object)
    UPS only. Adds custom COD number reference to UPS labels.

  - `extra.container_type` (string)
    Specify container type.

  - `extra.critical_pull_time` (string)
    Carrier arrival time to pickup packages from the fulfillment center. 
UTC format: %Y-%m-%dT%H:%M:%SZ

  - `extra.customer_branch` (string)
    Specify customer branch (Lasership only).

  - `extra.customer_reference` (object)
    Specify the reference field on the label (FedEx and UPS only).

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

  - `extra.customer_reference.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) |

  - `extra.dangerous_goods` (object)
    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.

  - `extra.dangerous_goods.contains` (boolean)
    Indicates if the shipment contains dangerous goods.

  - `extra.dangerous_goods.biological_material` (object)
    Container for specifying the presence of biological material.

  - `extra.dangerous_goods.biological_material.contains` (boolean)
    Indicates if the shipment contains biological material.

  - `extra.dangerous_goods.lithium_batteries` (object)
    Container for specifying the presence of lithium batteries.

  - `extra.dangerous_goods.lithium_batteries.contains` (boolean)
    Indicates if the shipment contains lithium batteries.

  - `extra.dangerous_goods_code` (any)
    Dangerous Goods Code (DHL eCommerce only). See Category Codes
    Enum: "01", "02", "03", "04", "05", "06", "07", "08", "09"

  - `extra.dealer_order_number` (object)
    UPS only. Adds custom dealer order number reference to UPS labels.

  - `extra.delivery_instructions` (string)
    Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only).

  - `extra.dept_number` (object)
    Specify the department number field on the label (FedEx and UPS only).

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

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

  - `extra.dry_ice` (object)
    Specify that the package contains Dry Ice (FedEx, Veho, and UPS only).

  - `extra.dry_ice.contains_dry_ice` (boolean)
    Mandatory. Specifies that the package contains Dry Ice.

  - `extra.dry_ice.weight` (string)
    Mandatory. Units must be in Kilograms. Cannot be greater than package weight.

  - `extra.fda_product_code` (object)
    UPS only. Adds custom FDA product code reference to UPS labels.

  - `extra.fulfillment_center` (string)
    The fulfilment center where the package originates from.

  - `extra.insurance` (object)
    To add 3rd party insurance powered by XCover, 
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.

  - `extra.insurance.amount` (string)
    Declared value of the goods you want to insure.
    Example: "5.5"

  - `extra.insurance.content` (string)
    Description of package content.

  - `extra.insurance.currency` (string)
    Currency for the amount value.
Currently only USD is supported for FedEx and UPS.
    Example: "USD"

  - `extra.insurance.provider` (any)
    To have insurance cover provided by a carrier directly instead of Shippo's provider (XCover), set provider to FEDEX, UPS, or ONTRAC.
    Enum: "FEDEX", "UPS", "ONTRAC"

  - `extra.invoice_number` (object)
    Specify the invoice number field on the label (FedEx and UPS only).

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

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

  - `extra.is_return` (boolean)
    This field specifies if it is a scan-based return shipment. See the Create a return shipment section for more details.

  - `extra.lasership_attrs` (array)
    Specify Lasership Attributes (Lasership only). Multiple options accepted.
    Enum: "TwoPersonDelivery", "Explosive", "Alcohol", "Hazmat", "ControlledSubstance", "Refrigerated", "DryIce", "Perishable", "NoRTS"

  - `extra.lasership_declared_value` (string)
    Declared value (Lasership only). Defaults to 50.00.

  - `extra.manifest_number` (object)
    UPS only. Adds custom manifest number reference to UPS labels.

  - `extra.model_number` (object)
    UPS only. Adds custom model number reference to UPS labels.

  - `extra.part_number` (object)
    UPS only. Adds custom part number reference to UPS labels.

  - `extra.po_number` (object)
    Specify the PO number field on the label (FedEx and UPS only).

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

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

  - `extra.preferred_delivery_timeframe` (any)
    Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is HHMMHHMM
    Enum: "10001200", "12001400", "14001600", "16001800", "18002000", "19002100"

  - `extra.premium` (boolean)
    Add premium service to a shipment (DHL Germany international shipments only).

  - `extra.production_code` (object)
    UPS only. Adds custom product code reference to UPS labels.

  - `extra.purchase_request_number` (object)
    UPS only. Adds custom purchase request number reference to UPS labels.

  - `extra.qr_code_requested` (boolean)
    Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only).

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

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

  - `extra.request_retail_rates` (boolean)
    Returns retail rates instead of account-based rates (UPS and FedEx only).

  - `extra.return_service_type` (string)
    Request additional return option for return shipments (UPS and Lasership only).

  - `extra.rma_number` (object)
    Specify the RMA number field on the label (FedEx and UPS only).

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

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

  - `extra.saturday_delivery` (boolean)
    Marks shipment as to be delivered on a Saturday.

  - `extra.salesperson_number` (object)
    UPS only. Adds custom salesperson number reference to UPS labels.

  - `extra.serial_number` (object)
    UPS only. Adds custom serial number reference to UPS labels.

  - `extra.signature_confirmation` (any)
    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).
    Enum: "STANDARD", "ADULT", "CERTIFIED", "INDIRECT", "CARRIER_CONFIRMATION"

  - `extra.store_number` (object)
    UPS only. Adds custom store number reference to UPS labels.

  - `extra.transaction_reference_number` (object)
    UPS only. Adds custom transaction reference number to UPS labels.

  - `extra.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.
    Example: "Customer ID 123456"

  - `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.
    Example: "2021-03-22T12:00:00Z"

  - `address_from` (any, required)

  - `address_return` (any)

  - `address_to` (any, required)

  - `customs_declaration` (any)

  - `async` (boolean)

  - `carrier_accounts` (array)
    List of Carrier Accounts object_ids used to filter 
the returned rates.  If set, only rates from these carriers will be returned.
    Example: ["065a4a8c10d24a34ab932163a1b87f52","73f706f4bdb94b54a337563840ce52b0"]

  - `parcels` (array, required)
    List of parcels to be shipped.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 30 items |

## Response 201 fields (application/json):

  - `extra` (object)
    An object holding optional extra services to be requested.

  - `extra.accounts_receivable_customer_account` (object)
    UPS only. Adds custom accounts receivable customer account reference to UPS labels.

  - `extra.accounts_receivable_customer_account.prefix` (string)
    Custom prefix text.
    Example: "ABC"

  - `extra.accounts_receivable_customer_account.value` (string)
    Label reference text. 35 character limit.
    Example: "value"

  - `extra.accounts_receivable_customer_account.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.
    Example: 1

  - `extra.alcohol` (object)
    Indicates that a shipment contains Alcohol (Fedex and UPS only).

  - `extra.alcohol.contains_alcohol` (boolean)
    Mandatory for Fedex and UPS. Specifies that the package contains Alcohol.

  - `extra.alcohol.recipient_type` (any)
    Mandatory for Fedex only. License type of the recipient of the Alcohol Package.
    Enum: "licensee", "consumer"

  - `extra.ancillary_endorsement` (any)
    Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only).
    Enum: "FORWARDING_SERVICE_REQUESTED", "RETURN_SERVICE_REQUESTED"

  - `extra.appropriation_number` (object)
    UPS only. Adds custom appropriation number reference to UPS labels.

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

  - `extra.bill_of_lading_number` (object)
    UPS only. Adds custom bill of lading number reference to UPS labels.

  - `extra.billing` (object)
    Specify billing details (UPS, FedEx, and DHL Germany only).

  - `extra.billing.account` (string)
    Account number to be billed. (For DHL Germany, leave this field blank.)

  - `extra.billing.country` (string)
    Country iso2 code of account number to be billed (required for UPS third party billing only).

  - `extra.billing.participation_code` (string)
    2 digit code used to override your default participation code associated with your DHL Germany account.

  - `extra.billing.type` (any)
    Party to be billed. (Leave blank for DHL Germany.)
    Enum: "SENDER", "RECIPIENT", "THIRD_PARTY", "THIRD_PARTY_CONSIGNEE", "COLLECT"

  - `extra.billing.zip` (string)
    ZIP code of account number to be billed (required for UPS if there is a zip on the billing account).

  - `extra.bypass_address_validation` (boolean)
    Bypasses address validation (USPS, UPS, & LaserShip only).

  - `extra.carbon_neutral` (boolean)
    Request carbon offsets by passing true (UPS only).

  - `extra.carrier_hub_id` (string)
    Identifies the carrier injection site.

  - `extra.carrier_hub_travel_time` (integer)
    Travel time in hours from fulfillment center to carrier injection site.

  - `extra.COD` (object)
    Specify collection on delivery details (UPS only).

  - `extra.COD.amount` (string)
    Amount to be collected.
    Example: "5.5"

  - `extra.COD.currency` (string)
    Currency for the amount to be collected. Currently only USD is supported for UPS.
    Example: "USD"

  - `extra.COD.payment_method` (string)
    Secured funds include money orders, certified cheques and others (see 
UPS for details). 
If no payment_method inputted the value defaults to "ANY".)
    Enum: "SECURED_FUNDS", "CASH", "ANY"

  - `extra.cod_number` (object)
    UPS only. Adds custom COD number reference to UPS labels.

  - `extra.container_type` (string)
    Specify container type.

  - `extra.critical_pull_time` (string)
    Carrier arrival time to pickup packages from the fulfillment center. 
UTC format: %Y-%m-%dT%H:%M:%SZ

  - `extra.customer_branch` (string)
    Specify customer branch (Lasership only).

  - `extra.customer_reference` (object)
    Specify the reference field on the label (FedEx and UPS only).

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

  - `extra.customer_reference.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) |

  - `extra.dangerous_goods` (object)
    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.

  - `extra.dangerous_goods.contains` (boolean)
    Indicates if the shipment contains dangerous goods.

  - `extra.dangerous_goods.biological_material` (object)
    Container for specifying the presence of biological material.

  - `extra.dangerous_goods.biological_material.contains` (boolean)
    Indicates if the shipment contains biological material.

  - `extra.dangerous_goods.lithium_batteries` (object)
    Container for specifying the presence of lithium batteries.

  - `extra.dangerous_goods.lithium_batteries.contains` (boolean)
    Indicates if the shipment contains lithium batteries.

  - `extra.dangerous_goods_code` (any)
    Dangerous Goods Code (DHL eCommerce only). See Category Codes
    Enum: "01", "02", "03", "04", "05", "06", "07", "08", "09"

  - `extra.dealer_order_number` (object)
    UPS only. Adds custom dealer order number reference to UPS labels.

  - `extra.delivery_instructions` (string)
    Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only).

  - `extra.dept_number` (object)
    Specify the department number field on the label (FedEx and UPS only).

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

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

  - `extra.dry_ice` (object)
    Specify that the package contains Dry Ice (FedEx, Veho, and UPS only).

  - `extra.dry_ice.contains_dry_ice` (boolean)
    Mandatory. Specifies that the package contains Dry Ice.

  - `extra.dry_ice.weight` (string)
    Mandatory. Units must be in Kilograms. Cannot be greater than package weight.

  - `extra.fda_product_code` (object)
    UPS only. Adds custom FDA product code reference to UPS labels.

  - `extra.fulfillment_center` (string)
    The fulfilment center where the package originates from.

  - `extra.insurance` (object)
    To add 3rd party insurance powered by XCover, 
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.

  - `extra.insurance.amount` (string)
    Declared value of the goods you want to insure.
    Example: "5.5"

  - `extra.insurance.content` (string)
    Description of package content.

  - `extra.insurance.currency` (string)
    Currency for the amount value.
Currently only USD is supported for FedEx and UPS.
    Example: "USD"

  - `extra.insurance.provider` (any)
    To have insurance cover provided by a carrier directly instead of Shippo's provider (XCover), set provider to FEDEX, UPS, or ONTRAC.
    Enum: "FEDEX", "UPS", "ONTRAC"

  - `extra.invoice_number` (object)
    Specify the invoice number field on the label (FedEx and UPS only).

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

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

  - `extra.is_return` (boolean)
    This field specifies if it is a scan-based return shipment. See the Create a return shipment section for more details.

  - `extra.lasership_attrs` (array)
    Specify Lasership Attributes (Lasership only). Multiple options accepted.
    Enum: "TwoPersonDelivery", "Explosive", "Alcohol", "Hazmat", "ControlledSubstance", "Refrigerated", "DryIce", "Perishable", "NoRTS"

  - `extra.lasership_declared_value` (string)
    Declared value (Lasership only). Defaults to 50.00.

  - `extra.manifest_number` (object)
    UPS only. Adds custom manifest number reference to UPS labels.

  - `extra.model_number` (object)
    UPS only. Adds custom model number reference to UPS labels.

  - `extra.part_number` (object)
    UPS only. Adds custom part number reference to UPS labels.

  - `extra.po_number` (object)
    Specify the PO number field on the label (FedEx and UPS only).

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

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

  - `extra.preferred_delivery_timeframe` (any)
    Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is HHMMHHMM
    Enum: "10001200", "12001400", "14001600", "16001800", "18002000", "19002100"

  - `extra.premium` (boolean)
    Add premium service to a shipment (DHL Germany international shipments only).

  - `extra.production_code` (object)
    UPS only. Adds custom product code reference to UPS labels.

  - `extra.purchase_request_number` (object)
    UPS only. Adds custom purchase request number reference to UPS labels.

  - `extra.qr_code_requested` (boolean)
    Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only).

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

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

  - `extra.request_retail_rates` (boolean)
    Returns retail rates instead of account-based rates (UPS and FedEx only).

  - `extra.return_service_type` (string)
    Request additional return option for return shipments (UPS and Lasership only).

  - `extra.rma_number` (object)
    Specify the RMA number field on the label (FedEx and UPS only).

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

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

  - `extra.saturday_delivery` (boolean)
    Marks shipment as to be delivered on a Saturday.

  - `extra.salesperson_number` (object)
    UPS only. Adds custom salesperson number reference to UPS labels.

  - `extra.serial_number` (object)
    UPS only. Adds custom serial number reference to UPS labels.

  - `extra.signature_confirmation` (any)
    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).
    Enum: "STANDARD", "ADULT", "CERTIFIED", "INDIRECT", "CARRIER_CONFIRMATION"

  - `extra.store_number` (object)
    UPS only. Adds custom store number reference to UPS labels.

  - `extra.transaction_reference_number` (object)
    UPS only. Adds custom transaction reference number to UPS labels.

  - `extra.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.
    Example: "Customer ID 123456"

  - `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.
    Example: "2021-03-22T12:00:00Z"

  - `address_from` (object, required)
    Address object of the sender / seller. Will be returned expanded by default.

  - `address_from.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) |
    Example: "Shwan Ippotle"

  - `address_from.company` (string)
    Company Name

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 35 characters; Either company or name required |
    Example: "Shippo"

  - `address_from.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 |
    Example: "215 Clayton St."

  - `address_from.street2` (string)
    Second street line.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |

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

  - `address_from.street_no` (string)
    Street number of the addressed building. 
This field can be included in street1 for all carriers except for DHL Germany.

  - `address_from.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 |
    Example: "San Francisco"

  - `address_from.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 |
    Example: "CA"

  - `address_from.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 |
    Example: "94117"

  - `address_from.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 for a list of country codes.
Sending a country is always required.
    Example: "US"

  - `address_from.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 |
    Example: "+1 555 341 9393"

  - `address_from.email` (string)
    E-mail address of the contact person, RFC3696/5321-compliant.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 80 characters |
    Example: "shippotle@shippo.com"

  - `address_from.is_residential` (boolean)
    Example: true

  - `address_from.metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you want 
to attach to the object.
    Example: "Customer ID 123456"

  - `address_from.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.
    Example: true

  - `address_from.latitude` (number,string)
    Latitude of address

  - `address_from.longitude` (number,string)
    Longitude of address

  - `address_from.object_created` (string)
    Date and time of Address creation.
    Example: "2014-07-09T02:19:13.174Z"

  - `address_from.object_id` (string)
    Unique identifier of the given Address object. 
This ID is required to create a Shipment object.
    Example: "d799c2679e644279b59fe661ac8fa488"

  - `address_from.object_owner` (string)
    Username of the user who created the Address object.
    Example: "shippotle@shippo.com"

  - `address_from.object_updated` (string)
    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.
    Example: "2014-07-09T02:19:13.174Z"

  - `address_from.validation_results` (object)
    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).

  - `address_from.validation_results.is_valid` (boolean)

  - `address_from.validation_results.messages` (array)

  - `address_from.validation_results.messages.code` (string)
    See Address Validation Codes
    Example: "Unknown Street"

  - `address_from.validation_results.messages.source` (string)
    See Address Validation Source
    Example: "Shippo Address Validator"

  - `address_from.validation_results.messages.text` (string)
    Example: "City, State and ZIP Code are valid, but street address is not a match."

  - `address_from.validation_results.messages.type` (string)
    Example: "address_warning"

  - `address_from.test` (boolean)
    Indicates whether the object has been created in test mode.

  - `address_return` (object)
    ID of the Address object where the shipment will be sent back to if it is not delivered 
(Only available for UPS, USPS, and Fedex shipments).  
If this field is not set, your shipments will be returned to the address_from.

  - `address_to` (object, required)
    Address object of the recipient / buyer. Will be returned expanded by default.

  - `carrier_accounts` (array, 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` (object)

  - `customs_declaration.aes_itn` (string)
    required if eel_pfc is AES_ITN
AES / ITN reference of the shipment.

  - `customs_declaration.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. 
Allowed values available here
    Example: "FILED_ELECTRONICALLY"

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

  - `customs_declaration.certificate` (string)
    Certificate reference of the shipment.

  - `customs_declaration.certify` (boolean, required)
    Expresses that the certify_signer has provided all information of this customs declaration truthfully.
    Example: true

  - `customs_declaration.certify_signer` (string, required)
    Name of the person who created the customs declaration and is responsible for the validity of all 
information provided.
    Example: "Shawn Ippotle"

  - `customs_declaration.commercial_invoice` (boolean)

  - `customs_declaration.contents_explanation` (string)
    required if contents_type is OTHER
Explanation of the type of goods of the shipment.
    Example: "T-Shirt purchase"

  - `customs_declaration.disclaimer` (string)
    Disclaimer for the shipment and customs information that have been provided.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 554 characters |

  - `customs_declaration.duties_payor` (object)
    Specifies who will pay the duties for the shipment. Only accepted for FedEx shipments.

  - `customs_declaration.duties_payor.account` (string)
    Account number to be billed for duties.
    Example: "2323434543"

  - `customs_declaration.duties_payor.type` (any)
    Party to be billed for duties.
    Enum: "SENDER", "RECIPIENT", "THIRD_PARTY"

  - `customs_declaration.duties_payor.address` (object)

  - `customs_declaration.duties_payor.address.name` (string)
    Name of the party to be billed for duties.
    Example: "Patrick Kavanagh"

  - `customs_declaration.duties_payor.address.zip` (string)
    Postal code of the party to be billed for duties.
    Example: "80331"

  - `customs_declaration.duties_payor.address.country` (string)
    Country ISO code of account number to be billed.
    Example: "DE"

  - `customs_declaration.exporter_identification` (object)
    Additional exporter identification that may be required to ship in certain countries

  - `customs_declaration.exporter_identification.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.
    Example: "PL123456790ABCDE"

  - `customs_declaration.exporter_identification.tax_id` (object)
    Tax identification that may be required to ship in certain countries. Typically used to assess duties on 
goods that are crossing a border.

  - `customs_declaration.exporter_identification.tax_id.number` (string)
    Tax identification number.
    Example: "123456789"

  - `customs_declaration.exporter_identification.tax_id.type` (any)
    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
    Enum: "EIN", "VAT", "IOSS", "ARN"

  - `customs_declaration.exporter_reference` (string)
    Exporter reference of an export shipment.

  - `customs_declaration.importer_reference` (string)
    Importer reference of an import shipment.

  - `customs_declaration.is_vat_collected` (boolean)
    Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.

  - `customs_declaration.invoice` (string)
    Invoice reference of the shipment.
    Example: "#123123"

  - `customs_declaration.license` (string)
    License reference of the shipment.

  - `customs_declaration.metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you 
want to attach to the object.
    Example: "Order ID #123123"

  - `customs_declaration.notes` (string)
    Additional notes to be included in the customs declaration.

  - `customs_declaration.address_importer` (string)
    Object ID of the Importer address.
    Example: "257ba08436604d2aaf069caafe7acb2a"

  - `customs_declaration.contents_type` (string, required)
    Type of goods of the shipment.  
Allowed values available here

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

  - `customs_declaration.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
Carrier-specific restrictions are in the table below.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Must be one of DDP, DDU, FCA, DAP |

  - `customs_declaration.invoiced_charges` (object)
    Additional invoiced charges to be shown on the Customs Declaration Commercial Invoice.

  - `customs_declaration.invoiced_charges.currency` (string, required)
    Currency for the invoiced charges amounts incurred on the end consumer.

  - `customs_declaration.invoiced_charges.total_shipping` (string)
    Total shipping paid by the buyer.

  - `customs_declaration.invoiced_charges.total_taxes` (string)
    Total taxes paid by the buyer.

  - `customs_declaration.invoiced_charges.total_duties` (string)
    Total duties paid by the buyer.

  - `customs_declaration.invoiced_charges.other_fees` (string)
    Other fees paid by the buyer.

  - `customs_declaration.items` (array, required)
    Distinct Parcel content items as Customs Items object_ids.
    Example: ["5087f181d1dc4b14b73fdbf636498886"]

  - `customs_declaration.non_delivery_option` (string, required)
    Indicates how the carrier should proceed in case the shipment can't be delivered.
Allowed values available here

  - `customs_declaration.object_created` (string)
    Date and time of object creation.
    Example: "2014-07-17T01:01:08.306Z"

  - `customs_declaration.object_id` (string)
    Unique identifier of the given object.
    Example: "e2197a54da9d470480f4f8796cc419cb"

  - `customs_declaration.object_owner` (string)
    Username of the user who created the object.
    Example: "shippotle@shippo.com"

  - `customs_declaration.object_state` (string)
    Indicates the validity of the enclosing object
    Enum: "VALID", "INVALID"

  - `customs_declaration.object_updated` (string)
    Date and time of last object update.
    Example: "2014-07-17T01:01:08.306Z"

  - `object_created` (string, required)
    Date and time of Shipment creation.

  - `object_id` (string, required)
    Unique identifier of the given Shipment object.
    Example: "adcfdddf8ec64b84ad22772bce3ea37a"

  - `object_owner` (string, required)
    Username of the user who created the Shipment object.
    Example: "pp@gmail.com"

  - `object_updated` (string, required)
    Date and time of last Shipment update.

  - `parcels` (array, required)
    List of Parcel objects to be shipped.

  - `parcels.extra` (object)
    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.

  - `parcels.extra.insurance` (object)
    To add insurance to your parcel, specify amount, content and currency. If you do not want to add insurance to you parcel, do not set these parameters.

  - `parcels.extra.insurance.content` (string)
    Description of parcel content.
    Example: "Laptop"

  - `parcels.extra.insurance.currency` (string)
    Currency for the amount value. Currently only USD is supported for FedEx and UPS.
    Example: "USD"

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

  - `parcels.metadata` (string)
    Example: "Customer ID 123456"

  - `parcels.mass_unit` (string, required)
    The unit used for weight.
    Enum: "g", "kg", "lb", "oz"

  - `parcels.weight` (string, required)
    Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
    Example: "1"

  - `parcels.distance_unit` (string, required)
    The measure unit used for length, width and height.
    Enum: "cm", "in", "ft", "m", "mm", "yd"

  - `parcels.height` (string, required)
    Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted.
    Example: "1"

  - `parcels.length` (string, required)
    Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
    Example: "1"

  - `parcels.width` (string, required)
    Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted.
    Example: "1"

  - `parcels.object_created` (string)
    Date and time of Parcel creation.
    Example: "2014-07-09T02:19:13.174Z"

  - `parcels.object_id` (string)
    Unique identifier of the given Parcel object. This ID is required to create a Shipment object.
    Example: "adcfdddf8ec64b84ad22772bce3ea37a"

  - `parcels.object_owner` (string)
    Username of the user who created the Parcel object.
    Example: "shippotle@shippo.com"

  - `parcels.object_state` (string)
    A Parcel will only be valid when all required values have been sent and validated successfully.
    Enum: "VALID"

  - `parcels.object_updated` (string)
    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.
    Example: "2014-07-09T02:19:13.174Z"

  - `parcels.template` (any)

  - `rates` (array, 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.

  - `rates.amount` (string, required)
    Final Rate price, expressed in the currency used in the sender's country.
    Example: "5.5"

  - `rates.amount_local` (string, required)
    Final Rate price, expressed in the currency used in the recipient's country.
    Example: "5.5"

  - `rates.currency` (string, required)
    Currency used in the sender's country, refers to amount. 
The official ISO 4217 currency codes are used, e.g. USD or EUR.
    Example: "USD"

  - `rates.currency_local` (string, required)
    Currency used in the recipient's country, refers to amount_local. 
The official ISO 4217 currency codes are used, e.g. USD or "EUR".
    Example: "USD"

  - `rates.arrives_by` (string)
    Predicted time the carrier will deliver the package in the destination's local time zone. In the format HH:MM:SS.
    Example: "08:30:00"

  - `rates.attributes` (array, required)
    An array containing specific attributes of this Rate in context of the entire shipment. 
Attributes can be assigned CHEAPEST, FASTEST, or BESTVALUE.
    Enum: "BESTVALUE", "CHEAPEST", "FASTEST"

  - `rates.carrier_account` (string, required)
    Object ID of the carrier account that has been used to retrieve the rate.
    Example: "078870331023437cb917f5187429b093"

  - `rates.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.
    Example: "Delivery in 1 to 3 business days"

  - `rates.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.
    Example: 2

  - `rates.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.
    Example: "1.05"

  - `rates.object_created` (string, required)
    Date and time of Rate creation.

  - `rates.object_id` (string, required)
    Unique identifier of the given Rate object.
    Example: "adcfdddf8ec64b84ad22772bce3ea37a"

  - `rates.object_owner` (string, required)
    Username of the user who created the rate object.
    Example: "pp@gmail.com"

  - `rates.provider` (string, required)
    Carrier offering the rate, e.g., FedEx or Deutsche Post DHL.
    Example: "USPS"

  - `rates.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.
    Example: "https://cdn2.goshippo.com/providers/75/USPS.png"

  - `rates.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.
    Example: "https://cdn2.goshippo.com/providers/200/USPS.png"

  - `rates.servicelevel` (object, required)
    Contains details regarding the service level for the given rate.

  - `rates.servicelevel.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.
    Example: "Priority Mail Express"

  - `rates.servicelevel.terms` (string)
    Further clarification of the service.

  - `rates.servicelevel.token` (string)
    Token of the Rate's servicelevel, e.g. usps_priority or fedex_ground. 
See servicelevels.
    Example: "usps_priority_express"

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

  - `rates.servicelevel.parent_servicelevel` (object)
    Contains details regarding the service level for the given rate.

  - `rates.shipment` (string, required)
    Example: "adcfdddf8ec64b84ad22772bce3ea37a"

  - `rates.zone` (string)
    The parcel's transit zone token. These tokens can vary depending on the provider.
    Example: "1"

  - `status` (string, 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.
    Enum: "ERROR", "QUEUED", "SUCCESS", "WAITING"