# Add shipments to a batch

Adds batch shipments to an existing batch.

Endpoint: POST /batches/{BatchId}/add_shipments
Version: 2018-02-08
Security: APIKeyHeader

## Path parameters:

  - `BatchId` (string, required)
    Object ID of the batch

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

  - `carrier_account` (string)
    Object ID of the carrier account to be used for this shipment (will override batch default)
    Example: "a4391cd4ab974f478f55dc08b5c8e3b3"

  - `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: "SHIPMENT #1"

  - `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 
or at this endpoint.
    Example: "fedex_ground"

  - `shipment` (object, required)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `shipment.address_from` (any, required)

  - `shipment.address_return` (any)

  - `shipment.address_to` (any, required)

  - `shipment.customs_declaration` (any)

  - `shipment.async` (boolean)

  - `shipment.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"]

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

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

## Response 200 fields (application/json):

  - `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.
    Example: "078870331023437cb917f5187429b093"

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

  - `label_filetype` (string)
    Print format of the label. If empty, will use the default format set from 
the Shippo dashboard.
    Enum: "PNG", "PNG_2.3x7.5", "PDF", "PDF_2.3x7.5", "PDF_4x6", "PDF_4x8", "PDF_A4", "PDF_A5", "PDF_A6", "ZPLII"

  - `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: "BATCH #1"

  - `batch_shipments` (object, required)
    Array of BatchShipment objects. 
The response keeps the same order as in the request array.

  - `batch_shipments.next` (string)
    Example: "baseurl?page=3&results=10"

  - `batch_shipments.previous` (string)
    Example: "baseurl?page=1&results=10"

  - `batch_shipments.results` (array)

  - `batch_shipments.results.carrier_account` (string)
    Object ID of the carrier account to be used for this shipment (will override batch default)
    Example: "a4391cd4ab974f478f55dc08b5c8e3b3"

  - `batch_shipments.results.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: "SHIPMENT #1"

  - `batch_shipments.results.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 
or at this endpoint.
    Example: "fedex_ground"

  - `batch_shipments.results.messages` (array)
    List of Shipment and Transaction error messages.

  - `batch_shipments.results.object_id` (string, required)
    Object ID of this batch shipment. Can be used in the remove_shipments endpoint.
    Example: "e11c95a6788d4ddcaa22f03175838740"

  - `batch_shipments.results.shipment` (string, required)
    Object ID of the shipment object created for this batch shipment.
    Example: "adcfdddf8ec64b84ad22772bce3ea37a"

  - `batch_shipments.results.status` (string, required)
    INVALID batch shipments cannot be purchased and will have to be removed, fixed, and added to the batch again.
VALID batch shipments can be purchased. 
Batch shipments with the status TRANSACTION_FAILED were not able to be purchased and the error will be displayed on the message field 
INCOMPLETE batch shipments have an issue with the Address and will need to be removed, fixed, and added to the batch again.
    Enum: "INVALID", "VALID", "INCOMPLETE", "TRANSACTION_FAILED"

  - `batch_shipments.results.transaction` (string)
    Object ID of the transaction object created for this batch shipment.
    Example: "4c33736a67e2450da88b38c42deef6b7"

  - `label_url` (array, 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
    Example: "2016-01-04T00:15:44.394Z"

  - `object_id` (string, required)
    Unique identifier of the given Batch object
    Example: "5ef63c54f5bf45d3b1f8fb37dcb1c5f4"

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

  - `object_results` (object, required)
    An object containing the following counts:creation_succeededcreation_failedpurchase_succeededpurchase_failed

  - `object_results.creation_failed` (integer, required)
    Example: 3

  - `object_results.creation_succeeded` (integer, required)
    Example: 5

  - `object_results.purchase_failed` (integer, required)

  - `object_results.purchase_succeeded` (integer, required)

  - `object_updated` (string, required)
    Date and time of last update to the Batch
    Example: "2016-01-04T00:48:13.841Z"

  - `status` (string, required)
    Batches that are VALIDATING are being created and validated
VALID batches can be purchased
INVALID batches cannot be purchased, INVALID BatchShipments must be removed
Batches that are in the PURCHASING state are being purchased
PURCHASED batches are finished purchasing.
    Enum: "VALIDATING", "VALID", "INVALID", "PURCHASING", "PURCHASED"

  - `test` (boolean)