---
title: "Add shipments to a batch"
method: POST
path: "/batches/{BatchId}/add_shipments"
tags: ["Batches"]
---

# Add shipments to a batch

`POST /batches/{BatchId}/add_shipments`

Adds batch shipments to an existing batch.

## Path parameters

- `BatchId` string, required

## Headers

- `SHIPPO-API-VERSION` string

## Request body

- BatchShipmentCreateRequest[]
  - `carrier_account` string — Object ID of the carrier account to be used for this shipment (will override batch default)
  - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
  - `servicelevel_token` string — A token that sets the shipping method for the batch, overriding the batch default. Servicelevel tokens can be found [in this list](/shippoapi/public-api/service-levels) or [at this endpoint](/shippoapi/public-api/carrier-accounts/listcarrieraccounts).
  - `shipment` ShipmentCreateRequest, required
    - `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).
              - …
            - `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.
              - …
            - `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).
              - …
            - `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.
              - …
            - `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 `200`

Batch

- Batch
  - `default_carrier_account` string, required — ID of the Carrier Account object to use as the default for all shipments in this Batch. The carrier account can be changed on a per-shipment basis by changing the carrier_account in the corresponding BatchShipment object.
  - `default_servicelevel_token` string, required — Token of the service level to use as the default for all shipments in this Batch. The servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the corresponding BatchShipment object. [Servicelevel tokens can be found here.](/shippoapi/public-api/service-levels)
  - `label_filetype` 'PNG' | 'PNG_2.3x7.5' | 'PDF' | 'PDF_2.3x7.5' | 'PDF_4x6' | 'PDF_4x8' | 'PDF_A4' | 'PDF_A5' | 'PDF_A6' | 'ZPLII' — Print format of the [label](https://docs.goshippo.com/docs/shipments/shippinglabelsizes/). If empty, will use the default format set from [the Shippo dashboard.](https://apps.goshippo.com/settings/labels)
  - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
  - `batch_shipments` BatchShipmentPaginatedList, required — Array of [BatchShipment](/shippoapi/public-api/batches/batchshipment) objects. The response keeps the same order as in the request array.
    - `next` string
    - `previous` string
    - `results` BatchShipment[]
      - `carrier_account` string — Object ID of the carrier account to be used for this shipment (will override batch default)
      - `metadata` string — A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
      - `servicelevel_token` string — A token that sets the shipping method for the batch, overriding the batch default. Servicelevel tokens can be found [in this list](/shippoapi/public-api/service-levels) or [at this endpoint](/shippoapi/public-api/carrier-accounts/listcarrieraccounts).
      - `messages` unknown[] — List of Shipment and Transaction error messages.
        - unknown
      - `object_id` string, required — Object ID of this batch shipment. Can be used in the remove_shipments endpoint.
      - `shipment` string, required — Object ID of the shipment object created for this batch shipment.
      - `status` 'INVALID' | 'VALID' | 'INCOMPLETE' | 'TRANSACTION_FAILED', required — - `INVALID`: the batch shipment cannot be purchased and will have to be removed, fixed, and added to the batch again - `VALID`: the batch shipment can be purchased - `TRANSACTION_FAILED`: the batch shipment was not able to be purchased and the error will be displayed on the message field - `INCOMPLETE`: the batch shipment has an issue with the Address and will need to be removed, fixed, and added to the batch again
      - `transaction` string — Object ID of the transaction object created for this batch shipment.
  - `label_url` string[], required — An array of URLs each pointing to a merged file of 100 labels each
  - `object_created` string, required — Date and time of Batch creation
  - `object_id` string, required — Unique identifier of the given Batch object
  - `object_owner` string, required — Username of the user who created the Batch object.
  - `object_results` object, required — An object containing the following counts: `creation_succeeded`, `creation_failed`, `purchase_succeeded`, `purchase_failed`
    - `creation_failed` integer, required
    - `creation_succeeded` integer, required
    - `purchase_failed` integer, required
    - `purchase_succeeded` integer, required
  - `object_updated` string, required — Date and time of last update to the Batch
  - `status` 'VALIDATING' | 'VALID' | 'INVALID' | 'PURCHASING' | 'PURCHASED', required — - `VALIDATING`: the batch is being created and validated - `VALID`: the batch can be purchased - `INVALID`: the batch cannot be purchased; `INVALID` BatchShipments must be removed - `PURCHASING`: the batch is being purchased - `PURCHASED`: the batch is finished purchasing
  - `test` boolean

## 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)