For AI agents: visit https://docs.shipium.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI.
# About multi-parcel shipments [Skip link to About multi-parcel shipments](https://docs.shipium.com/docs/multi-parcel-shipments\#about-multi-parcel-shipments)
Grouping packages together into one shipment with one tracking number for the same delivery destination might be of benefit to your organization. You might be shipping multiple items for which you wish to have separate packages to the same recipient, or you might have a large order of multiple items filling more than one package to ship to the same recipient. For either case, one tracking number can allow you to track all packages in the shipment.
This document instructs you on how to call Shipium's Carrier and Method Selection with Label Single Call API to rate shop the best carrier service method for a multi-parcel shipment. The [Carrier and Method Selection & Shipment Label API](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api) document provides an overview of special cases that can be handled when calling the API. Those same cases are supported for multi-parcel shipments as well.
## Multi-parcel rating types [Skip link to Multi-parcel rating types](https://docs.shipium.com/docs/multi-parcel-shipments\#multi-parcel-rating-types)
There are four types of multi-parcel rating in the Shipium system:
1. **Individual parcels (default).** The system rates each parcel individually and then sums the individual parcel rates. This method aligns with how some carriers rate shipments by aggregating individual package billable weights.
2. **Combined weights.** The system calculates the billable weight for each parcel individually, then sums these billable weights to get a total shipment weight, and finally applies a single rate based on this total combined weight for the entire shipment. This approach is typically used by carriers that price multi-parcel shipments based on the aggregated weight of all packages, rather than summing individual package rates.
3. **Combined weights or individual parcels.** This rating type instructs the system to consider both aggregated shipment-level rating and individual parcel rating. It first checks if individual packages or the total shipment exceed specific carrier thresholds that would prevent combined rating. If no such restrictions apply, the system calculates rates for both methods and selects the less expensive option. This provides flexibility while adhering to carrier-specific rules.
4. **None.** When multi-parcel shipments are not supported for the service method, there is no multi-parcel rating. The system uses regular parcel rating in this case.
Carriers generally have dimension and weight threshold requirements that a shipment must meet at the package and shipment levels in order to be considered for multi-parcel shipment pricing. The carrier's requirements for each service method determine the rating type(s) for which the shipment qualifies to be considered. Carrier-specific requirements are described in the following section. Shipium recommends consulting specific carriers' service guides to understand their multi-parcel rating methodology. Misconfiguration of the rating type can lead to incorrect rates.
## Carrier specifics related to multi-parcel shipments [Skip link to Carrier specifics related to multi-parcel shipments](https://docs.shipium.com/docs/multi-parcel-shipments\#carrier-specifics-related-to-multi-parcel-shipments)
The Shipium platform supports multi-parcel shipments for carriers including FedEx, FlavorCloud, Global-e, Midland, Uber, and UPS shipping in the U.S. and Canada. In addition, you can use multi-parcel shipping for Intelcom, Obibox, and Purolator in Canada and for Orchestro in the U.S.
Some carrier restrictions for multi-parcel shipping at the service level (standard, ground, etc.) and/or service method level determine the type of rating (listed in the previous section) that Shipium will use during carrier selection. In order for a multi-parcel shipment to be considered for the _combined weights or individual parcels_ rating type described in item 3 in the previous section, the packages must meet the following service method requirements:
- Package-Level Minimum & Maximum Thresholds
- Dimensions (e.g., max length of 119 inches per package)
- Weight (e.g., min of 15 pounds per package)
- Shipment-Level Minimum & Maximum Thresholds
- Dimensions (e.g., max combined length of 200 inches)
- Weight (e.g., min combined weight of 100 pounds)
- Shipment Deficit Pricing. Shipment weight is rounded to a specified weight if conditions are met (e.g., if a shipment weighs 151-199 pounds, it’s rounded up to a shipment weight of 200 for rating purposes).
- Rounding Strategy. Individual parcel weights are rounded up to the ceiling integer value before being summed (e.g., 65.4 + 44.3 + 21.8 would actually be 66 + 45 + 22).
Carrier-specific requirements are included in the individual sections that follow.
### FedEx [Skip link to FedEx](https://docs.shipium.com/docs/multi-parcel-shipments\#fedex)
Multi-parcel shipping is available via FedEx Express (domestic and international), FedEx Ground, and FedEx International Ground. Requirements by carrier service level are included in the following table.
| Requirement | FedEx Express (domestic) | FedEx Express (international) | FedEx Ground (domestic) | FedEx International Ground (to Canada) |
| --- | --- | --- | --- | --- |
| **Minimum Total Shipment Weight** | 100 lbs.
(200 lbs. for FedEx Express Saver) | 100 lbs. | 200 lbs. | 150 lbs. |
| **Minimum Weight** | 15 lbs. per package (average) | 100 lbs. total shipment
(no per-package minimum) | 15–25 lbs. per package (average) | 15–20 lbs. per package (average) |
| **Maximum Weight** | 150 lbs. per package | 150 lbs. per package | 150 lbs. per package | 150 lbs. per package |
| **Maximum Dimensions (per package)** | - 119" length
- 165" length plus girth (L+2H+2W) | - 108" length
- 130" length plus girth (L+2W+2H) | - 108" length
- 165" length plus girth (L+2H+2W) | - 108" length
- 130" length plus girth (L+2W+2H) |
| **Other** | - Calculated for up to 999 packages in a single shipment
- Allows deficit pricing, rounding up to 100 lbs. if your shipment is close to that weight | - No multiweight enablement required on shipments weighing more than 100 lbs.; multiweight pricing automatically applies
- Calculated for up to 999 packages in a single shipment
- If shipments are palletized and weigh 151 lbs. or more, they are rated as FedEx International Priority Freight or FedEx International Economy Freight | Allows deficit pricing, rounding up to 200 lbs. if your shipment is 151–199 lbs. | Not Applicable |
### UPS [Skip link to UPS](https://docs.shipium.com/docs/multi-parcel-shipments\#ups)
UPS supports multi-parcel shipment pricing for shipments weighing over 150 pounds in total weight for UPS Worldwide Express Plus, UPS Worldwide Express NA1, UPS Worldwide Express, UPS Worldwide Express Freight Midday, UPS Worldwide Express Freight, UPS Worldwide Saver, UPS Worldwide Expedited, UPS 3 Day Select from Canada, and UPS Standard.
UPS has the following qualification requirements for a shipment to be considered for multi-parcel pricing:
- The shipment must consist of multiple packages using the same service method, shipped on the same day to a single recipient.
- The shipment's parcels should be aggregated for pricing prior to printing a label.
- When combined shipment weight is being calculated, each individual parcel is rounded using the ceiling approach before these values are summed. For example, individual parcel weights for three packages with weights of 65.4 pounds, 44.3 pounds, and 21.8 pounds would be rounded to 66, 45, and 22, respectively, before being rate shopped via carrier selection.
- Shipment pricing does not apply to UPS Express Envelopes, the UPS 10 KG Box, or the UPS 25 KG Box; they are each considered separate shipments.
- Unless otherwise specified at the time of shipping, shipping charges are billed to the shipper.
- For a multi-parcel UPS Standard shipment, the minimum charge will be based on an average weight of 15 pounds per package.
## Weights in multi-parcel shipments [Skip link to Weights in multi-parcel shipments](https://docs.shipium.com/docs/multi-parcel-shipments\#weights-in-multi-parcel-shipments)
Multi-parcel shipments involve specific weight handling to ensure accurate carrier rating. Understanding how Shipium calculates and applies weight fields helps you interpret API responses and troubleshoot rating discrepancies.
When you create a multi-parcel shipment, the rate calculation response includes multiple weight fields:
JSON
```json
{
"carrierServiceMethodId": "ups-ground",
"physicalWeight": 24.7,
"actualWeight": 25.0,
"dimWeight": 18.3,
"billableWeight": 25.0,
"weightUnitForRate": "lb"
}
```
- **Physical weight (`physicalWeight`).** The sum of the actual, physical weights of all packages in the shipment as measured on a scale, including contents and packaging materials
- **Dimensional weight (`dimWeight`).** A calculated weight that accounts for the space the packages occupy. Calculated using (Length × Width × Height) / dimensional factor.
- **Rounded weight (`actualWeight`).** The physical weight rounded according to carrier and Shipium's internal business rules. For multi-parcel shipments with certain carriers, this value may be used in rate calculations instead of the raw physical weight.
- **Billable weight (`billableWeight`).** The weight carriers use to look up rates in their rate tables. Determined by comparing the appropriate weight (physical or rounded, depending on carrier) with dimensional weight, taking the greater value, then rounding up to the next weight increment in the carrier's rate sheet. This ensures the billable weight aligns with the carrier's discrete pricing tiers and is guaranteed to be the same or higher than both comparison weights.
> 📘
>
> ### API and Shipium Console terminology [Skip link to API and Shipium Console terminology](https://docs.shipium.com/docs/multi-parcel-shipments\#api-and-shipium-console-terminology)
>
> The API field `actual_weight` represents rounded weight. In the Shipium Console, this field is labeled "Rounded Weight." Both terms refer to the same calculated value.
### How weight affects multi-parcel rating [Skip link to How weight affects multi-parcel rating](https://docs.shipium.com/docs/multi-parcel-shipments\#how-weight-affects-multi-parcel-rating)
For multi-parcel shipments, weight handling varies by carrier:
**Carriers using rounded weight for rating:**
- UPS multi-parcel shipments
- FedEx multi-parcel shipments
- Other carriers configured with specific rounding requirements
**Carriers using physical weight for rating:**
- USPS multi-parcel shipments
- Regional carriers without rounding requirements
- Most other carriers
In both cases, the carrier compares the appropriate weight (rounded or physical) against dimensional weight, takes the greater value, then rounds up to the carrier's rate table to determine the final billable weight used for cost calculation.
### Understanding the weight calculation [Skip link to Understanding the weight calculation](https://docs.shipium.com/docs/multi-parcel-shipments\#understanding-the-weight-calculation)
1. **Physical weight** is measured for each package.
2. **Physical weight** is summed across all packages in the multi-parcel shipment.
3. **Rounded weight** is calculated by applying carrier-specific rounding rules.
4. **Dimensional weight** is calculated based on package dimensions.
5. **Greater weight** is determined by comparing the appropriate weight (rounded or physical) with dimensional weight.
6. **Billable weight** is determined by rounding up to the next increment in the carrier's rate table (ceiling).
For carriers requiring rounded weight in multi-parcel calculations, rounded weight is compared with dimensional weight. For other carriers, physical weight is compared with dimensional weight. The greater value is then rounded up to match the carrier's rate sheet increments to determine the final billable weight used for pricing.
### Important notes [Skip link to Important notes](https://docs.shipium.com/docs/multi-parcel-shipments\#important-notes)
- **Rounding rules.** The specific rounding algorithm is based on carrier requirements and Shipium's internal business rules and is subject to change. Contact Shipium support if you need details about current rounding behavior for your integration.
- **Single-parcel vs. multi-parcel.** For single-parcel shipments, rounded weight appears in API responses but is not used for rate calculations. Standard billable weight determination (greater of physical weight or dimensional weight, rounded to rate sheet entry) applies.
- **Dimensional weight impact.** Even in multi-parcel shipments, dimensional weight can significantly impact costs. Large, lightweight packages may have dimensional weights that exceed physical or rounded weights, making dimensional weight the basis for billable weight calculation.
- **Rate sheet ceiling.** Billable weight always rounds up to the next increment in the carrier's rate table. A multi-parcel shipment with a calculated weight of 24.7 lbs will have a billable weight of 25 lbs (assuming whole pound increments).
- **Weight units.** All weight fields in the response use the same unit, specified in `weightUnitForRate`.
## Payor specification for multi-parcel shipments [Skip link to Payor specification for multi-parcel shipments](https://docs.shipium.com/docs/multi-parcel-shipments\#payor-specification-for-multi-parcel-shipments)
You can specify multiple payors for a multi-parcel shipment by including payor account information in your API calls. Specifying payors responsible for a shipment via API call overrides any configurations your organization may have in the Shipium Console.
The [Specifying Payors](https://docs.shipium.com/docs/specifying-payors) documentation provides details about how to bill multiple payor accounts separately for costs associated with a shipment.
# Select a carrier service method (with or without generating a label) for a multi-parcel shipment [Skip link to Select a carrier service method (with or without generating a label) for a multi-parcel shipment](https://docs.shipium.com/docs/multi-parcel-shipments\#select-a-carrier-service-method-with-or-without-generating-a-label-for-a-multi-parcel-shipment)
To determine the least expensive carrier and ship method for a multi-parcel shipment, and generate a shipment label, you'll use the example request body below. To run carrier selection without retrieving a label, however, you will need to change the `generateLabel` value from "true" to "false".
> 👍
>
> ### Test Mode [Skip link to Test Mode](https://docs.shipium.com/docs/multi-parcel-shipments\#test-mode)
>
> _Want to run some examples and not charge any real money against your account?_
>
> You can add "testMode": "true" to the data passed to any label call to retrieve labels without charging money in a carrier-specific manner. Most carriers will mark their labels in a way to make clear that they are void, such as inserting "VOID" throughout the label or using a predefined ID.
>
> **The examples below all contain the`testMode` flag to err on the side of caution – remove this to make production calls.**
The example request body follows that of the typical Carrier and Method Selection with Label Single Call, with the addition of the `multiParcelShipmentParameters` parameter.
> 📘
>
> ### Using a partner shipment ID [Skip link to Using a partner shipment ID](https://docs.shipium.com/docs/multi-parcel-shipments\#using-a-partner-shipment-id)
>
> You can include an optional `partnerShipmentId` in the `multiParcelShipmentParameters` of your request. This unique identifier can be used to reference the shipment in your own systems. The `partnerShipmentId` will be returned in the response and can be used for tracking and reconciliation purposes. When creating a shipment, if a `partnerShipmentId` is provided, it can be used in place of the `shipiumShipmentId` in subsequent API calls that take a shipment identifier as a path parameter.
## Request fields for API calls for multi-parcel shipments [Skip link to Request fields for API calls for multi-parcel shipments](https://docs.shipium.com/docs/multi-parcel-shipments\#request-fields-for-api-calls-for-multi-parcel-shipments)
The following tables provide required, conditional, and optional field descriptions for calling to rate shop and retrieve a label for a multi-parcel shipment. Some optional fields are represented in the international example. You can find additional support in the [Carrier and Method Selection & Shipment Label API Reference](https://docs.shipium.com/reference/runmegashipmentprocessv1).
### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/multi-parcel-shipments\#required-fields)
| Field | Details |
| --- | --- |
| `multiParcelShipmentParameters .orderedDateTime` | **Type:** String (date-time)
**Description:** The timestamp for when the customer placed the order for this product; the timestamp must be a valid [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp. |
| `multiParcelShipmentParameters .destinationAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for the destination address |
| `multiParcelShipmentParameters .destinationAddress.postalCode` | **Type:** String
**Description:** A country-code-appropriate postal code for the address |
| `multiParcelShipmentParameters .destinationAddress.countryCode` | **Type:** String
**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats#per-country-details) for the address |
| `multiParcelShipmentParameters.packages .orderItemQuantities.productId` | **Type:** String
**Description:** A product ID for the product being checked (ISBN, UPC, etc.) |
| `multiParcelShipmentParameters.packages .orderItemQuantities.quantity` | **Type:** Integer (int32)
**Description:** The number of units of the product |
### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/multi-parcel-shipments\#conditional-fields)
| Field | Details |
| --- | --- |
| `multiParcelShipmentParameters.originId` | **Type:** String
**Condition:** If you opt to include an `originId` in your call, the `shipFromAddress` should not be included.
**Description:** Either the Shipium-generated origin ID or your organization's own origin ID, used to identify the origin where the shipment will be processed |
| `multiParcelShipmentParameters.shipFromAddress .postalCode` | **Type:** String
**Condition:** If you opt to include an `originId` in your call, the `shipFromAddress` should not be included.
**Description:** A country-code-appropriate postal code for the address |
| `multiParcelShipmentParameters.shipFromAddress .countryCode` | **Type:** String
**Condition:** If you opt to include an `originId` in your call, the `shipFromAddress` should not be included.
**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats#per-country-details) for the address |
| `multiParcelShipmentParameters.returnToAddress .countryCode` | **Type:** String
**Condition:** Required if including a `returnToAddress`
**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats#per-country-details) for the address of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters.returnToAddress .postalCode` | **Type:** String
**Condition:** Required if including a `returnToAddress`
**Description:** A country code appropriate postal code for the address of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters.packages .orderItemQuantities.productDetails` | **Type:** Array of strings
**Values:**`limited_quantity` (preferred for LQ/ORM-D; alias: `lq`), `bound_printed_matter` (alias: `bpm`), `perishable`, `ormd` (legacy; alias: `orm-d`)
**Condition:** Required for [international shipments](https://docs.shipium.com/docs/customs-info-api-example-definitions) and shipments containing [hazardous materials](https://docs.shipium.com/docs/hazardous-materials-support)
**Description:** A list of product properties that affect carrier selection and handling; see [productDetails Reference](https://docs.shipium.com/docs/hazardous-materials-support#productdetails-reference) for details. |
| `multiParcelShipmentParameters.packages .packagingType.linearDimensions.height` | **Type:** Number (float)
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).
**Description:** The least long linear dimension (i.e., the shortest side of a box or envelope)
**Note on envelopes:** This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions. |
| `multiParcelShipmentParameters.packages .packagingType.linearDimensions.length` | **Type:** Number (float)
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).
**Description:** The longest linear dimension (i.e., the longest side of a box or envelope) |
| `multiParcelShipmentParameters.packages .packagingType.linearDimensions.linearUnit` | **Type:** String (enumeration)
**Values:**`cm` (centimeter), `in` (inch)
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).
**Description:** The unit in which linear dimensions are provided |
| `multiParcelShipmentParameters.packages .packagingType.linearDimensions.width` | **Type:** Number (float)
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).
**Description:** The second longest linear dimension (i.e., the second longest side of a box or envelope) |
| `multiParcelShipmentParameters.packages .packagingType.packagingMaterial` | **Type:** String (enumeration)
**Values:**`box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet`
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if the `packagingMaterial` is not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration) associated with the `packagingTypeId`.
**Description:** The material type of the packaging |
| `multiParcelShipmentParameters.packages .packagingType.packagingTypeId` | **Type:** String
**Example:**`ebd94f8b-d390-4c9c-987f-b88343f5bf45`
**Condition:** When this value is present, `linearDimensions` and `packagingMaterial` become optional. When this value is absent, `linearDimensions` and `packagingMaterial` are required.
**Description:** The unique identifier for a [pre-configured packaging type](https://docs.shipium.com/docs/shipium-carrier-selection-configuring-package-sizes) defined in the Shipium Console. When provided, the system uses the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration) properties (dimensions, material, weight) associated with this ID. |
### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/multi-parcel-shipments\#optional-fields)
| Field | Details |
| --- | --- |
| `currencyCode` | **Type:** String
**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `generateLabel` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, a request to the selected carrier will be sent to generate a [label](https://docs.shipium.com/docs/carrier-shipment-label-flow) for the shipment based on the information provided in the `labelParameters` field of this object. When `false`, this step is skipped and the system will record what carrier service method would have generated a label for. |
| `ignoreRuleSets` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, any configured [rule sets](https://docs.shipium.com/docs/carrier-selection-rules) will be ignored during carrier selection. |
| `labelParameters.currencyCode` | **Type:** String
**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |
| `labelParameters .includeLabelImagesInResponse` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, the response will include the raw image data of the [labels](https://docs.shipium.com/docs/carrier-shipment-label-flow) that were requested to be generated by the carrier. |
| `labelParameters.labelFormats` | **Type:** String (enumeration)
**Values:**`pdf`, `png`, `zpl`
**Description:** List of formats in which to generate the package [label](https://docs.shipium.com/docs/carrier-shipment-label-flow) |
| `labelParameters .eligibleForManifest` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, or null, this label will be included in end-of-day and scheduled [manifests](https://docs.shipium.com/docs/shipment-manifesting). `False` indicates that the label should not be included in any manifests. |
| `multiParcelShipmentParameters .partnerShipmentId` | **Type:** String
**Description:** An optional unique identifier that may be used for the shipment |
| `multiParcelShipmentParameters .fulfillmentContext` | **Type:** String
**Description:** The name of the [fulfillment context](https://docs.shipium.com/docs/fulfillment-contexts); this is used to limit carrier selection to carrier accounts that contain a matching fulfillment context. |
| `multiParcelShipmentParameters .shippedDateTime` | **Type:** String (date-time)
**Description:** The timestamp for when a partner shipped the product from their warehouse; the timestamp must be a valid [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp. If not provided, this value defaults to `orderedDateTime`. |
| `multiParcelShipmentParameters .desiredDeliveryDate` | **Type:** String
**Example:**`2019-10-31T20:00:00Z`
**Description:** The string representation of either an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date or a LocalDate: `yyyy-mm-dd`. The date or date-time the package is intended to arrive to the customer. This is used to determine the most appropriate service method when generating a label. |
| `multiParcelShipmentParameters .testMode` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, a [test mode](https://docs.shipium.com/docs/understanding-carrier-selection-label-test-mode) shipment will be created. Carrier selection will consider carriers and service methods in test mode, and label generation will generate a test label. |
| `multiParcelShipmentParameters .destinationAddress.street1` | **Type:** String
**Description:** The first address line |
| `multiParcelShipmentParameters .destinationAddress.city` | **Type:** String
**Description:** The name of the city for the destination address |
| `multiParcelShipmentParameters .destinationAddress.state` | **Type:** String
**Description:** The 2-letter postal abbreviation of the state for the destination address |
| `multiParcelShipmentParameters .destinationAddress.name` | **Type:** String
**Description:** The name of the contact for the destination address |
| `multiParcelShipmentParameters .destinationAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact for the destination address |
| `multiParcelShipmentParameters .shipFromAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for the address |
| `multiParcelShipmentParameters .shipFromAddress.city` | **Type:** String
**Description:** The name of the city for the address |
| `multiParcelShipmentParameters .shipFromAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact for the address |
| `multiParcelShipmentParameters .shipFromAddress.state` | **Type:** String
**Description:** The 2-letter postal abbreviation of the state for the address |
| `multiParcelShipmentParameters .shipFromAddress.company` | **Type:** String
**Description:** The company name for the address |
| `multiParcelShipmentParameters .shipFromAddress.name` | **Type:** String
**Description:** The name of the contact for the address |
| `multiParcelShipmentParameters .shipFromAddress.street1` | **Type:** String
**Description:** The first address line |
| `multiParcelShipmentParameters .shipFromAddress.street2` | **Type:** String
**Description:** The second address line |
| `multiParcelShipmentParameters .useShipFromAddressInRequest` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, this optional field overrides the shipper's contact name and address configured for the shipping origin in the Shipium Console, opting to use the `shipFromAddress` information passed in the API call.
**Note:** If shipping with carrier [LaserShip](https://docs.shipium.com/docs/lasership), use caution with this flag as the carrier's strict address matching could result in an error. |
| `multiParcelshipmentParameters .emergencyResponseInfo` | **Type:** Object
**Description:** Emergency response contact details for hazmat shipments. Contains optional fields for `phoneNumber` ( _String_, max 25 characters), `contactName` ( _String_, max 35 characters), and `contractNumber` ( _String_, max 35 characters). When not provided, the system falls back to `shipFromAddress` contact information. Supported by UPS and FedEx. See [Hazardous Materials](https://docs.shipium.com/docs/hazardous-materials-support) for field details and carrier-specific guidance. |
| `multiParcelShipmentParameters .returnToAddress.name` | **Type:** String
**Description:** The name associated with the address of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact associated with the address of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress .phoneNumberCountryCode` | **Type:** String
**Description:** The phone number country code of the contact associated with the address of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress.emailAddress` | **Type:** String
**Description:** The email address of the contact associated with the address of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress.company` | **Type:** String
**Description:** The company of the contact associated with the address of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress.street1` | **Type:** String
**Description:** The first address line of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress.street2` | **Type:** String
**Description:** The second address line of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress.city` | **Type:** String
**Description:** The city of the location where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress.state` | **Type:** String
**Description:** The 2-letter abbreviation of the location's state where the package is being returned; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .returnToAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for the return-to address; this [return-to address](https://docs.shipium.com/docs/fulfillment-contexts#return-to-address-override-details) will override a return-to address configured for an origin or carrier account. |
| `multiParcelShipmentParameters .packages.orderItemQuantities .shipiumOrderId` | **Type:** String
**Description:** Identification used to represent the group of delivery estimates purchased |
| `multiParcelShipmentParameters .packages.orderItemQuantities .hazmat` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, this indicates that the item is [hazardous material](https://docs.shipium.com/docs/hazardous-materials-support) (hazmat). The default value is `false`. |
| `multiParcelShipmentParameters .orderItemQuantities .orderItemReferenceIdentifier` | **Type:** String
**Example:**`someIdentifier`
**Description:** An external identifier that can reference the order item that exists in an external order management system (OMS). This field will be passed to supported carriers. |
| `multiParcelShipmentParameters .orderItemQuantities.productTaxCode` | **Type:** String
**Description:** The tax code that applies to the given product |
| `multiParcelShipmentParameters .orderItemQuantities.itemWeight .weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)
**Description:** The unit in which weight values are provided |
| `multiParcelShipmentParameters .orderItemQuantities.itemWeight .weight` | **Type:** Number (float)
**Example:**`50`
**Description:** The value of the weight |
| `multiParcelShipmentParameters .packages.packagingType .packagingSizeName` | **Type:** String
**Example:**`13x12x10 box`
**Description:** A custom name for the packaging |
| `multiParcelShipmentParameters .packages.packagingType .packagingWeight.weight` | **Type:** Number (float)
**Description:** The value of the weight |
| `multiParcelShipmentParameters .packages.packagingType .packagingWeight.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)
**Description:** The unit in which weight values are provided |
| `multiParcelShipmentParameters .packages.totalWeight.weight` | **Type:** Number (float)
**Description:** The value of the weight |
| `multiParcelShipmentParameters .packages.totalWeight.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)
**Description:** The unit in which weight values are provided |
| `multiParcelShipmentParameters .packages.packageReferenceIdentifier` | **Type:** String
**Description:** Used to correlate parcels to label documents from the carrier |
| `multiParcelShipmentParameters .packages.partnerProvidedPackageId` | **Type:** String
**Description:** A unique identifier you wish to associate with this package |
| `multiParcelShipmentParameters .partnerReferenceIdentifier` | **Type:** String
**Description:** String provided by your organization that is passed to carriers as a reference |
| `multiParcelShipmentParameters .partnerReferenceIdentifier2` | **Type:** String
**Description:** String provided by your organization that is passed to carriers as a reference2 |
## Minimal example for a multi-parcel shipment [Skip link to Minimal example for a multi-parcel shipment](https://docs.shipium.com/docs/multi-parcel-shipments\#minimal-example-for-a-multi-parcel-shipment)
### Example cURL request [Skip link to Example cURL request](https://docs.shipium.com/docs/multi-parcel-shipments\#example-curl-request)
This example shows the cURL request.
cURL
```curl
curl --request POST \
--url https://api.shipium.com/api/v1/shipment/carrierselection/label \
--header 'accept: application/json' \
--header $AUTHSTRING \
--header 'content-type: application/json' \
--data 'INSERT REQUEST BODY FROM BELOW'
```
### Example request body [Skip link to Example request body](https://docs.shipium.com/docs/multi-parcel-shipments\#example-request-body)
This example shows the minimum fields required for the JSON request body.
JSON
```json
{
"currencyCode": "usd",
"generateLabel": true,
"labelParameters": {
"currencyCode": "usd",
"includeLabelImagesInResponse": true,
"labelFormats": [\
"zpl"\
],
"eligibleForManifest": true
},
"multiParcelShipmentParameters": {
"partnerShipmentId": "myCustomPartnerShipmentId123",
"fulfillmentContext": "fulfillment-context",
"shippedDateTime": "2023-09-06T18:30:55.558Z",
"orderedDateTime": "2022-04-07T18:30:55.558Z",
"testMode": true,
"destinationAddress": {
"addressType": "residential",
"street1": "100 Main St.",
"city": "Elk City",
"state": "CO",
"postalCode": "80026",
"countryCode": "US",
"name": "John Doe",
"phoneNumber": "2062652733"
},
"shipFromAddress": {
"addressType": "commercial",
"city": "Pottsville",
"phoneNumber": "6612475319",
"state": "PA",
"postalCode": "17901",
"company": "Sell It",
"name": "PAFC",
"street1": "401 N. Centre St.",
"street2": "",
"countryCode": "US"
},
"returnToAddress": {
"name": "Rod Runner",
"phoneNumber": "865-433-9999",
"phoneNumberCountryCode": "+2",
"emailAddress": "rod@acme.com",
"company": "ACME",
"street1": "456 Main St.",
"street2": "Suite 8",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"packages": [\
{\
"orderItemQuantities": [\
{\
"shipiumOrderId": 123,\
"productId": "ET-14-4000",\
"quantity": 2,\
"productDetails": [],\
"hazmat": false\
},\
{\
"productId": "7G-100-0756",\
"quantity": 1,\
"productDetails": [],\
"hazmat": false\
}\
],\
"packagingType": {\
"linearDimensions": {\
"height": 10,\
"length": 13,\
"linearUnit": "in",\
"width": 12\
},\
"packagingMaterial": "box",\
"packagingSizeName": "13x12x10 box",\
"packagingWeight": {\
"weight": 50,\
"weightUnit": "lb"\
}\
},\
"totalWeight": {\
"weight": 50,\
"weightUnit": "lb"\
},\
"packageReferenceIdentifier": "package1",\
"partnerProvidedPackageId": "13_in_box"\
},\
{\
"orderItemQuantities": [\
{\
"shipiumOrderId": 123,\
"productId": "ET-14-4000",\
"quantity": 2,\
"productDetails": [],\
"hazmat": false\
},\
{\
"productId": "7G-100-0756",\
"quantity": 1,\
"productDetails": [],\
"hazmat": false\
}\
],\
"packagingType": {\
"linearDimensions": {\
"height": 10,\
"length": 13,\
"linearUnit": "in",\
"width": 12\
},\
"packagingMaterial": "box",\
"packagingSizeName": "13x12x10 box",\
"packagingWeight": {\
"weight": 50,\
"weightUnit": "lb"\
}\
},\
"packageReferenceIdentifier": "package2",\
"totalWeight": {\
"weight": 50,\
"weightUnit": "lb"\
}\
}\
]
}
}
```
### Example response body [Skip link to Example response body](https://docs.shipium.com/docs/multi-parcel-shipments\#example-response-body)
The `packages` array in the following example is automatically included in a response for a multi-parcel request.
JSON
```json
{
"shipiumShipmentId": "2557feb7-63e7-4842-9303-46ef8da5e5b6",
"partnerShipmentId": "myCustomPartnerShipmentId123",
"orderedDateTime": "2024-04-10T15:15:14Z",
"shippedDateTime": "2024-04-10T15:15:14Z",
"ignoreUpgradeSpendLimits": false,
"fulfillmentType": "customer",
"packages": [\
{\
"packageReferenceIdentifier": "package1",\
"orderItemQuantities": [\
{\
"productId": "ET-14-4000",\
"quantity": 2,\
"productDetails": [],\
"shipiumOrderId": "123",\
"hazmat": false\
},\
{\
"productId": "7G-100-0756",\
"quantity": 1,\
"productDetails": [],\
"hazmat": false\
}\
],\
"packagingType": {\
"packagingMaterial": "box",\
"packagingSizeName": "13x12x10 box",\
"linearDimensions": {\
"linearUnit": "in",\
"length": 13,\
"width": 12,\
"height": 10\
},\
"packagingWeight": {\
"weightUnit": "lb",\
"weight": 50\
}\
},\
"totalWeight": {\
"weightUnit": "lb",\
"weight": 50\
}\
},\
{\
"packageReferenceIdentifier": "package2",\
"partnerProvidedPackageId": "13_in_box",\
"orderItemQuantities": [\
{\
"productId": "ET-14-4000",\
"quantity": 2,\
"productDetails": [],\
"shipiumOrderId": "123",\
"hazmat": false\
},\
{\
"productId": "7G-100-0756",\
"quantity": 1,\
"productDetails": [],\
"hazmat": false\
}\
],\
"packagingType": {\
"packagingMaterial": "box",\
"packagingSizeName": "13x12x10 box",\
"linearDimensions": {\
"linearUnit": "in",\
"length": 13,\
"width": 12,\
"height": 11\
},\
"packagingWeight": {\
"weightUnit": "lb",\
"weight": 50\
}\
},\
"totalWeight": {\
"weightUnit": "lb",\
"weight": 50\
}\
}\
],
"orderItemQuantities": [\
{\
"productId": "ET-14-4000",\
"quantity": 2,\
"productDetails": [],\
"shipiumOrderId": "123",\
"hazmat": false\
},\
{\
"productId": "7G-100-0756",\
"quantity": 1,\
"productDetails": [],\
"hazmat": false\
},\
{\
"productId": "ET-14-4000",\
"quantity": 2,\
"productDetails": [],\
"shipiumOrderId": "123",\
"hazmat": false\
},\
{\
"productId": "7G-100-0756",\
"quantity": 1,\
"productDetails": [],\
"hazmat": false\
}\
],
"destinationAddress": {
"name": "John Doe",
"phoneNumber": "2062652733",
"street1": "100 Main St.",
"city": "Elk City",
"state": "CO",
"countryCode": "US",
"postalCode": "80026",
"addressType": "residential"
},
"shipFromAddress": {
"name": "Ro Drunner",
"phoneNumber": "6612475319",
"phoneNumberCountryCode": "MX",
"emailAddress": "rodrunner@sellit.com",
"company": "Sell It",
"street1": "401 N. Centre St.",
"city": "Pottsville",
"state": "PA",
"countryCode": "US",
"postalCode": "17901"
},
"returnToAddress": {
"name": "Rod Runner",
"phoneNumber": "865-433-9999",
"phoneNumberCountryCode": "+2",
"emailAddress": "rod@acme.com",
"company": "ACME",
"street1": "456 Main St.",
"street2": "Suite 8",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"fulfillmentContextId": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab",
"requestFulfillmentContextIds": [],
"originId": "5a1ea728-4ba2-4cc6-892c-1f122f350775",
"shipmentTags": [],
"carrierSelection": {
"status": "success",
"statusDetails": "success",
"carrierSelectionId": "46089d8a-0f31-441d-a8b5-97b56bd8ebdc",
"shipiumShipmentId": "2557feb7-63e7-4842-9303-46ef8da5e5b6",
"partnerId": "76abb3d4-8990-4f80-aa13-4c2007cb852a",
"carrierAccountId": "625db658-e091-4e1b-888a-321270c8e6af",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtaG9tZS1kZWxpdmVyeS1zZXJ2aWNlLW1ldGhvZDo6N2JiYjY5NzMtYWVkYi00YTcwLWFjMDctMjIwY2JiMzdjYjIwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
"carrier": "fedex",
"carrierServiceMethodId": "fedex-home-delivery-service-method",
"serviceMethodName": "FedEx Home Delivery",
"totalCost": 25.12,
"carrierCompareCost": 25.12,
"carrierInvoiceCost": 25.12,
"operationalCost": 25.12,
"thirdPartyBilling": false,
"carrierSelectionDateTime": "2024-04-10T15:15:13.799Z",
"carrierZoneId": "fedex-zone-7"
},
"carrierLabel": {
"shipiumShipmentId": "2557feb7-63e7-4842-9303-46ef8da5e5b6",
"carrierSelectionId": "46089d8a-0f31-441d-a8b5-97b56bd8ebdc",
"shipiumLabelId": "cd5af1ab-ce6c-4811-9130-a4896b1e541c",
"status": "success",
"statusDetails": "success",
"effectiveShipDateTime": "2024-04-10T15:21:38.21Z",
"labelCreationDateTime": "2024-04-10T15:21:41.275Z",
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtaG9tZS1kZWxpdmVyeS1zZXJ2aWNlLW1ldGhvZDo6N2JiYjY5NzMtYWVkYi00YTcwLWFjMDctMjIwY2JiMzdjYjIwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",
"carrier": "fedex",
"carrierServiceName": "FedEx Corporation Account - 2",
"serviceMethodName": "FedEx Home Delivery",
"carrierServiceMethodId": "fedex-home-delivery-service-method",
"carrierShipmentId": "794622958747",
"carrierTrackingId": "794622958747",
"shipiumTrackingId": "52483a58-0788-4cf5-a2b4-b06610097158",
"carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622958747",
"carrierLabelCurrencyCode": "usd",
"carrierLabelPrice": 25.12,
"billableWeight": {
"weightUnit": "lb",
"weight": 6
},
"documents": [\
{\
"labelExpiration": "2024-04-24T15:21:41.250860462Z",\
"labelFormat": "zpl",\
"labelProperties": {\
"height": 4,\
"width": 6,\
"linearUnits": "in",\
"dpi": 203,\
"labelOrientation": "rotate_0"\
},\
"labelImage": {\
"imageEncoding": "base64",\
"imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMjg2XkdCNzU1LDIsMl5GUwpeRk8xMiw1NTJeR0I3NzcsMiwyXkZTCl5GTzMyLDE2NV5BZE4sMCwwXkZXTl5GSF5GREZST006XkZTCl5GTzMyLDE4MV5BZE4sMCwwXkZXTl5GSF5GRE1hYyBCcm93bl5GUwpeRk8zMiwxOTleQWROLDAsMF5GV05eRkheRkRTYWtzIE9mZiA1dGheRlMKXkZPMzIsMjE3XkFkTiwwLDBeRldOXkZIXkZEMjUgS2V5c3RvbmUgQmx2ZF5GUwpeRk8zMiwyMzVeQWROLDAsMF5GV05eRkheRkReRlMKXkZPMzIsMjcxXkFkTiwwLDBeRldOXkZIXkZEVVMgXkZTCl5GTzIyNCwxNjVeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8yOCw5MDReQTBOLDI0LDI0XkZXTl5GSF5GRFRSSyNeRlMKXkZPMjgsOTYyXkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPMTM2LDg3NF5BME4sMjcsMzZeRldOXkZIXkZEXkZTCl5GTzMyLDI1M15BZE4sMCwwXkZXTl5GSF5GRFBvdHRzdmlsbGUgUEEgMTc5MDFeRlMKXkZPNDc4LDE2NV5BZE4sMCwwXkZXTl5GSF5GRFNISVAgREFURTogMTBBUFIyNF5GUwpeRk80NzgsMTgxXkFkTiwwLDBeRldOXkZIXkZEQUNUV0dUOiAwLjgxIExCXkZTCl5GTzQ3OCwxOTleQWROLDAsMF5GV05eRkheRkRDQUQ6IDAwMDAwMDAvV1NYSTM2MDBeRlMKXkZPNDc4LDI1M15BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzM5LDI5OF5BME4sMzksMzleRldOXkZIXkZESm9obiBEb2VeRlMKXkZPMzksMzQwXkEwTiwzOSwzOV5GV05eRkheRkReRlMKXkZPMzksMzgyXkEwTiwzOSwzOV5GV05eRkheRkRQLk8gQm94OiA4MDc3XkZTCl5GTzM5LDQyNF5BME4sMzksMzleRldOXkZIXkZEKipURVNUIExBQkVMIC0gRE8gTk9UIFNISVAqKl5GUwpeRk8zOSw1MDleQWROLDAsMF5GV05eRkheRkQoMjA2KSAyNjUtMjczM15GUwpeRk8zOSw0NjZeQTBOLDQzLDQwXkZXTl5GSF5GREVsayBDaXR5IENPIDgwMDI2XkZTCl5GTzcxOSw0NjZeQTBOLDQzLDQwXkZXTl5GSF5GRChVUyleRlMKXkZPNjc3LDYyNF5HQjEwNCwxMCwxMF5GUwpeRk82NzcsNjM0XkdCMTAsMTEyLDEwXkZTCl5GTzc3MSw2MzReR0IxMCwxMTIsMTBeRlMKXkZPNjc3LDc0Nl5HQjEwNCwxMCwxMF5GUwpeRk80NjQsMTYwXkdCMiwxMjYsMl5GUwpeRk82ODcsNjQyXkEwTiwxMjgsMTM3XkZXTl5GSF5GREheRlMKXkZPNjU0LDU2NF5BME4sNDMsNTheRldOXkZIXkZERmVkRXheRlMKXkZPNjYzLDYxMF5BYk4sMTEsN15GV05eRkheRkRIb21lIERlbGl2ZXJ5XkZTCl5GTzc5MSw2NTVeQTBOLDEzLDE4XkZXQl5GSF5GREoyNDIwMjQwNDA0MDF1dl5GUwpeRk85LDI5OF5BME4sMjEsMjFeRldOXkZIXkZEVE9eRlMKXkZPMjEsNTc0XkJZMiwyXkI3TiwxMCw1LDE0XkZIXkZXTl5GSF5GRFspPl8xRTAxXzFEMDI4MDAyNl8xRDg0MF8xRDgwNF8xRDc5NDYyMjk1ODc0N18xREZERUdfMUQ4MDAwMzAyXzFEMTAxXzFEXzFEMS8xXzFEMC44MUxCXzFETl8xRFAuTyBCb3g6IDgwNzdfMURFbGsgQ2l0eV8xRENPXzFESm9obiBEb2VfMUUwNl8xRDEwWkdIMDA3XzFEMTJaMjA2MjY1MjczM18xRDIwWl8xQ18xRDMxWjk2MjIwODA0MzAwMDgwMDAzMDI5MDA3OTQ2MjI5NTg3NDdfMURfMUVfMDReRlMKXkZPMjgsOTk5XkEwTiwxMDcsOTZeRldOXkZIXkZEXkZTCl5GTzEyLDg0M15HQjc3NywyLDJeRlMKXkZPNDk0LDEwNDdeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83ODgsMTkwXkFiTiwxMSw3XkZXQl5GSF5GRDU4M0o2LzBGRUMvOUFFM15GUwpeRk85NSw5MDheQTBOLDUzLDQwXkZXTl5GSF5GRDAwMDAgMDAwMCAwMDAwXkZTCl5GTzQwOSw4NTdeQTBOLDUxLDM4XkZXTl5GSF5GQjM5MCwsLFIsXkZEICAgICAgICAgICAgICAgICAgIF5GUwpeRk80MDQsOTA5XkEwTiw1MSwzOF5GV05eRkheRkI0MDAsLCxSLF5GRCAgICAgICAgICAgICAgICAgICBeRlMKXkZPNDEzLDk2MV5BME4sNDAsNDBeRldOXkZIXkZCMzg2LCwsUixeRkQgICAgICAgICAgICAgICAgXkZTCl5GTzQ5NSwxMDAzXkEwTiw0NCw0NF5GV05eRkheRkIyOTgsLCxSLF5GRCAgICAgODAwMjZeRlMKXkZPNTc0LDEwNjNeQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEICAgICAgXkZTCl5GTzY5NSwxMDQ3XkEwTiw0Myw0M15GV05eRkheRkIxMDAsLCxSLF5GRCAgIF5GUwpeRk8zOSwxMDg5XkEwTiwyNywzNl5GV05eRkheRkQwMDAwIDAwMDAgMCAoMDAwIDAwMCAwMDAwKSAwIDAwIDAwMDAgMDAwMCAwMDAwXkZTCl5GTzc1LDExMzBeQlkzLDJeQkNOLDIwMCxOLE4sTixOXkZXTl5GRD47OTYyMjA4MDQzMDAwODAwMDMwMjkwMDAwMDAwMDAwMDAwMF5GUwpeRk8xMzUsMTE5MF5BME4sMTI4LDEzN15GV05eRkheRkRTQU1QTEVeRlMKXkZPNDc4LDIxN15BZE4sMCwwXkZXTl5GSF5GRERJTU1FRDogMTUgWCAxMCBYIDUgSU5eRlMKXkZPMzI5LDUxMV5BYk4sMTEsN15GV05eRkheRkRSRUY6IF5GUwpeRk8zOSw1MjVeQWJOLDExLDdeRldOXkZIXkZESU5WOiBeRlMKXkZPMzksNTM5XkFiTiwxMSw3XkZXTl5GSF5GRFBPOiBeRlMKXkZPNDI5LDUzOV5BYk4sMTEsN15GV05eRkheRkRERVBUOiBeRlMKXlBRMQpeWFoK"\
},\
"labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/70d9b16f-c2a4-4a74-baa7-f1b40a41b91d/carrierSelection/7f4ae98d-8f20-413b-9c86-65613ee12614/label/cd5af1ab-ce6c-4811-9130-a4896b1e541c/zpl",\
"carrierTrackingId": "794622958747",\
"carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622958747",\
"packageReferenceIdentifier": "package1",\
"carrierShipmentId": "794622958747"\
},\
{\
"labelExpiration": "2024-04-24T15:21:41.250860462Z",\
"labelFormat": "zpl",\
"labelProperties": {\
"height": 4,\
"width": 6,\
"linearUnits": "in",\
"dpi": 203,\
"labelOrientation": "rotate_0"\
},\
"labelImage": {\
"imageEncoding": "base64",\
"imageContents": "XlhBXkNGLDAsMCwwXlBSMTJeTUQzMF5QT0leQ0kxM15MSDAsMjAKXkZPMTIsMjg2XkdCNzU1LDIsMl5GUwpeRk8xMiw1NTJeR0I3NzcsMiwyXkZTCl5GTzMyLDE2NV5BZE4sMCwwXkZXTl5GSF5GREZST006XkZTCl5GTzMyLDE4MV5BZE4sMCwwXkZXTl5GSF5GRE1hYyBCcm93bl5GUwpeRk8zMiwxOTleQWROLDAsMF5GV05eRkheRkRTYWtzIE9mZiA1dGheRlMKXkZPMzIsMjE3XkFkTiwwLDBeRldOXkZIXkZEMjUgS2V5c3RvbmUgQmx2ZF5GUwpeRk8zMiwyMzVeQWROLDAsMF5GV05eRkheRkReRlMKXkZPMzIsMjcxXkFkTiwwLDBeRldOXkZIXkZEVVMgXkZTCl5GTzIyNCwxNjVeQWROLDAsMF5GV05eRkheRkQoMjE1KSA1NTUtNTU1NV5GUwpeRk8yOCw5MDReQTBOLDI0LDI0XkZXTl5GSF5GRFRSSyNeRlMKXkZPMjgsOTYyXkEwTiwyNywzMl5GV05eRkheRkReRlMKXkZPMTM2LDg3NF5BME4sMjcsMzZeRldOXkZIXkZEXkZTCl5GTzMyLDI1M15BZE4sMCwwXkZXTl5GSF5GRFBvdHRzdmlsbGUgUEEgMTc5MDFeRlMKXkZPNDc4LDE2NV5BZE4sMCwwXkZXTl5GSF5GRFNISVAgREFURTogMTBBUFIyNF5GUwpeRk80NzgsMTgxXkFkTiwwLDBeRldOXkZIXkZEQUNUV0dUOiAwLjgxIExCXkZTCl5GTzQ3OCwxOTleQWROLDAsMF5GV05eRkheRkRDQUQ6IDAwMDAwMDAvV1NYSTM2MDBeRlMKXkZPNDc4LDI1M15BZE4sMCwwXkZXTl5GSF5GREJJTEwgU0VOREVSXkZTCl5GTzM5LDI5OF5BME4sMzksMzleRldOXkZIXkZESm9obiBEb2VeRlMKXkZPMzksMzQwXkEwTiwzOSwzOV5GV05eRkheRkReRlMKXkZPMzksMzgyXkEwTiwzOSwzOV5GV05eRkheRkRQLk8gQm94OiA4MDc3XkZTCl5GTzM5LDQyNF5BME4sMzksMzleRldOXkZIXkZEKipURVNUIExBQkVMIC0gRE8gTk9UIFNISVAqKl5GUwpeRk8zOSw1MDleQWROLDAsMF5GV05eRkheRkQoMjA2KSAyNjUtMjczM15GUwpeRk8zOSw0NjZeQTBOLDQzLDQwXkZXTl5GSF5GREVsayBDaXR5IENPIDgwMDI2XkZTCl5GTzcxOSw0NjZeQTBOLDQzLDQwXkZXTl5GSF5GRChVUyleRlMKXkZPNjc3LDYyNF5HQjEwNCwxMCwxMF5GUwpeRk82NzcsNjM0XkdCMTAsMTEyLDEwXkZTCl5GTzc3MSw2MzReR0IxMCwxMTIsMTBeRlMKXkZPNjc3LDc0Nl5HQjEwNCwxMCwxMF5GUwpeRk80NjQsMTYwXkdCMiwxMjYsMl5GUwpeRk82ODcsNjQyXkEwTiwxMjgsMTM3XkZXTl5GSF5GREheRlMKXkZPNjU0LDU2NF5BME4sNDMsNTheRldOXkZIXkZERmVkRXheRlMKXkZPNjYzLDYxMF5BYk4sMTEsN15GV05eRkheRkRIb21lIERlbGl2ZXJ5XkZTCl5GTzc5MSw2NTVeQTBOLDEzLDE4XkZXQl5GSF5GREoyNDIwMjQwNDA0MDF1dl5GUwpeRk85LDI5OF5BME4sMjEsMjFeRldOXkZIXkZEVE9eRlMKXkZPMjEsNTc0XkJZMiwyXkI3TiwxMCw1LDE0XkZIXkZXTl5GSF5GRFspPl8xRTAxXzFEMDI4MDAyNl8xRDg0MF8xRDgwNF8xRDc5NDYyMjk1ODc0N18xREZERUdfMUQ4MDAwMzAyXzFEMTAxXzFEXzFEMS8xXzFEMC44MUxCXzFETl8xRFAuTyBCb3g6IDgwNzdfMURFbGsgQ2l0eV8xRENPXzFESm9obiBEb2VfMUUwNl8xRDEwWkdIMDA3XzFEMTJaMjA2MjY1MjczM18xRDIwWl8xQ18xRDMxWjk2MjIwODA0MzAwMDgwMDAzMDI5MDA3OTQ2MjI5NTg3NDdfMURfMUVfMDReRlMKXkZPMjgsOTk5XkEwTiwxMDcsOTZeRldOXkZIXkZEXkZTCl5GTzEyLDg0M15HQjc3NywyLDJeRlMKXkZPNDk0LDEwNDdeQTBOLDQzLDQzXkZXTl5GSF5GRF5GUwpeRk83ODgsMTkwXkFiTiwxMSw3XkZXQl5GSF5GRDU4M0o2LzBGRUMvOUFFM15GUwpeRk85NSw5MDheQTBOLDUzLDQwXkZXTl5GSF5GRDAwMDAgMDAwMCAwMDAwXkZTCl5GTzQwOSw4NTdeQTBOLDUxLDM4XkZXTl5GSF5GQjM5MCwsLFIsXkZEICAgICAgICAgICAgICAgICAgIF5GUwpeRk80MDQsOTA5XkEwTiw1MSwzOF5GV05eRkheRkI0MDAsLCxSLF5GRCAgICAgICAgICAgICAgICAgICBeRlMKXkZPNDEzLDk2MV5BME4sNDAsNDBeRldOXkZIXkZCMzg2LCwsUixeRkQgICAgICAgICAgICAgICAgXkZTCl5GTzQ5NSwxMDAzXkEwTiw0NCw0NF5GV05eRkheRkIyOTgsLCxSLF5GRCAgICAgODAwMjZeRlMKXkZPNTc0LDEwNjNeQTBOLDI0LDI0XkZXTl5GSF5GQjEyMCwsLFIsXkZEICAgICAgXkZTCl5GTzY5NSwxMDQ3XkEwTiw0Myw0M15GV05eRkheRkIxMDAsLCxSLF5GRCAgIF5GUwpeRk8zOSwxMDg5XkEwTiwyNywzNl5GV05eRkheRkQwMDAwIDAwMDAgMCAoMDAwIDAwMCAwMDAwKSAwIDAwIDAwMDAgMDAwMCAwMDAwXkZTCl5GTzc1LDExMzBeQlkzLDJeQkNOLDIwMCxOLE4sTixOXkZXTl5GRD47OTYyMjA4MDQzMDAwODAwMDMwMjkwMDAwMDAwMDAwMDAwMF5GUwpeRk8xMzUsMTE5MF5BME4sMTI4LDEzN15GV05eRkheRkRTQU1QTEVeRlMKXkZPNDc4LDIxN15BZE4sMCwwXkZXTl5GSF5GRERJTU1FRDogMTUgWCAxMCBYIDUgSU5eRlMKXkZPMzI5LDUxMV5BYk4sMTEsN15GV05eRkheRkRSRUY6IF5GUwpeRk8zOSw1MjVeQWJOLDExLDdeRldOXkZIXkZESU5WOiBeRlMKXkZPMzksNTM5XkFiTiwxMSw3XkZXTl5GSF5GRFBPOiBeRlMKXkZPNDI5LDUzOV5BYk4sMTEsN15GV05eRkheRkRERVBUOiBeRlMKXlBRMQpeWFoK"\
},\
"labelUrl": "https://shiptime-service.stage.shipium.com/api/v1/deliveryexperience/shipment/70d9b16f-c2a4-4a74-baa7-f1b40a41b91d/carrierSelection/7f4ae98d-8f20-413b-9c86-65613ee12614/label/cd5af1ab-ce6c-4811-9130-a4896b1e541c/zpl",\
"carrierTrackingId": "794622964205",\
"carrierTrackingLink": "https://wsbeta.fedex.com/fedextrack/?trknbr=794622964205",\
"packageReferenceIdentifier": "package2",\
"carrierShipmentId": "794622964205"\
}\
],
"internationalDocuments": [],
"labelFailoverOccurred": false,
"testMode": true,
"multiParcel": true
},
"saturdayDelivery": false,
"deliverySignatureOption": "None",
"forceThirdPartyBilling": false,
"fulfillmentContext": "fulfillment-context",
"createdWithVersion": "v2",
"multiParcel": true,
"testMode": true
}
```
## International example for a multi-parcel shipment [Skip link to International example for a multi-parcel shipment](https://docs.shipium.com/docs/multi-parcel-shipments\#international-example-for-a-multi-parcel-shipment)
For international shipments, you'll need to add a `customsInfo` object within `multiParcelShipmentParameters`, whose fields are defined in the following tables. Other fields included in the sample call are defined in the table above. For additional support, you can refer to [Customs Info for Shipments](https://docs.shipium.com/docs/customs-info-api-example-definitions).
### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/multi-parcel-shipments\#required-fields-1)
| Field | Details |
| --- | --- |
| `multiParcelShipmentParameters.customsInfo .totalCustomsValue` | **Type:** Number (float)
**Description:** The customs value of the shipment in `totalCustomsValueCurrency` |
| `multiParcelShipmentParameters.customsInfo .totalCustomsValueCurrency` | **Type:** String
**Description:** The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code representing the `totalCustomsValue` |
| `multiParcelShipmentParameters.customsInfo .customsDescription` | **Type:** String
**Description:** The detailed description of the items being shipped |
| `multiParcelShipmentParameters.customsInfo .reasonForExport` | **Type:** String (enumeration)
**Values:**`sale`, `gift`, `sample`, `returns`, `personal_effects`
**Description:** The reason to export an international shipment |
| `multiParcelShipmentParameters.customsInfo .invoiceDate` | **Type:** String
**Description:** Date when the invoice was created; ideally this is the same as the ship date. |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.name` | **Type:** String
**Description:** The name associated with the address |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact for the address |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.countryCode` | **Type:** String
**Description:** The [ISO-3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats#per-country-details) for the address |
| `multiParcelShipmentParameters.customsInfo .electronicExportInformation` | **Type:** Electronic Export Information object (see below)
**Description:** Information for the Electronic Export Information (EEI) customs form, only used when the EEI will be filed directly by the carrier (i.e., not filed by your organization using AESDirect or otherwise) |
| `multiParcelShipmentParameters.customsInfo .electronicExportInformation.exportDate` | **Type:** String (date-time)
**Description:** The date the goods will be leaving the country in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format |
| `multiParcelShipmentParameters.customsInfo .electronicExportInformation.pointOfOrigin` | **Type:** String
**Description:** The 2-character state abbreviation from which the goods were shipped |
| `multiParcelShipmentParameters.customsInfo .customsItems.customsValue` | **Type:** Number (float)
**Description:** The value of each individual item to report to customs in `customsValueCurrency` |
| `multiParcelShipmentParameters.customsInfo .customsItems.customsValueCurrency` | **Type:** String
**Description:** The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code representing the `totalCustomsValue` |
| `multiParcelShipmentParameters.customsInfo .customsItems.commodityDescription` | **Type:** String
**Description:** A description of this product to be provided to customs |
| `multiParcelShipmentParameters.customsInfo .customsItems.countryOfManufacture` | **Type:** String
**Description:** The [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats#per-country-details) for the address |
| `multiParcelShipmentParameters.customsInfo .customsItems.customsWeight.weight` | **Type:** Number (float)
**Description:** The weight of the item to report to customs in units of `weightUnit` |
| `multiParcelShipmentParameters.customsInfo .customsItems.customsWeight.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)
**Description:** The weight unit |
| `multiParcelShipmentParameters.customsInfo .customsItems.quantity` | **Type:** Number (integer)
**Description:** The number of units of this customs item |
| `multiParcelShipmentParameters.customsInfo .customsItems.quantityUnitOfMeasurement` | **Type:** String (enumeration)
**Values:**`bag`, `barrel`, `box`, `case_of_goods`, `container`, `crate`, `cylinder`, `envelope`, `pallet`, `piece`, `roll`, `tube`
**Description:** The unit of measurement of the item |
| `multiParcelShipmentParameters.customsInfo .customsItems.harmonizedTariffNumber` | **Type:** String
**Description:** The 6- to 15-digit Harmonized System Tariff classification code |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .exportType` | **Type:** String (enumeration)
**Values:**`domestic`, `foreign`
**Description:** The type of the export |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .exportInformationCode` | **Type:** String
**Description:** The 2-character export information code for the commodity |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .scheduleBInformation.scheduleBNumber` | **Type:** String
**Description:** The 10-digit Schedule B classification code for the item being exported |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .scheduleBInformation.scheduleBQuantity` | **Type:** Number (integer)
**Description:** The count of how many Schedule B units are in the shipment |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .scheduleBInformation.scheduleBUnitOfMeasurement` | **Type:** String (enumeration)
**Values:**`barrels`, `carat`, `content_kilogram`, `square_centimeter`, `content_ton`, `curie`, `clean_yield_kilogram`, `dozen`, `dozen_pieces`, `dozen_pairs`, `fiber_meter`, `gross_container`, `gram`, `gross`, `hundred`, `kilogram`, `cubic_kilometer`, `kilogram_total_sugars`, `liter`, `meter`, `square_meter`, `cubic_meter`, `millicurie`, `number`, `pieces`, `proof_liter`, `pack`, `pairs`, `running_bales`, `square`, `ton`, `thousand`, `no_quantity_required`
**Description:** The unit of measure for the Schedule B quantity |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .eccnNumber` | **Type:** String
**Description:** The 5-digit product Export Control Classification Number (ECCN) number as issued by the Bureau of Industry and Security; the format is `#A###`. |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .exportLicenseInformation.licenseType` | **Type:** String
**Description:** The standard license type code as published by the U.S. government |
### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/multi-parcel-shipments\#conditional-fields-1)
| Field | Details |
| --- | --- |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .exportLicenseInformation.exportLicense.licenseNumber` | **Type:** String
**Condition:** Required if the license type requires a valid license; not needed if you have provided a `licenseExemptionCode`
**Description:** The license number |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .exportLicenseInformation.exportLicense.licenseLineValue` | **Type:** Number (integer)
**Condition:** Required if the license type requires a valid license; not needed if you have provided a `licenseExemptionCode`
**Description:** The export monetary amount allowed per license |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .exportLicenseInformation.exportLicense.licenseExpiration` | **Type:** String
**Condition:** Required if the license type requires a valid license; not needed if you have provided a `licenseExemptionCode`
**Description:** The license expiration date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format |
### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/multi-parcel-shipments\#optional-fields-1)
| Field | Details |
| --- | --- |
| `multiParcelShipmentParameters.customsInfo .TaxIdentificationNumber` | **Type:** String
**Example:**`12345`
**Description:** This optional value can be passed to override any tax ID number (also known as an employer identification number, or EIN) that is configured in your network settings (e.g., at the [tenant level](https://docs.shipium.com/docs/fulfillment-contexts#tenant-details) for a fulfillment context), on a per-shipment basis. This value also can be passed in `shipmentParameters` for a [single-parcel shipment](https://docs.shipium.com/docs/carrier-and-method-selection-and-shipment-label-api). You can find more information in [Tax Identification Number](https://docs.shipium.com/docs/tax-identification-number). |
| `multiParcelShipmentParameters.customsInfo .invoiceNumber` | **Type:** String
**Description:** The Commercial Invoice number, if the Commercial Invoice was generated by your organization |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress` | **Type:** Address object (see below) **Description:** The person or company who receives the goods for end use; if no value is sent, Shipium will use the `destinationAddress`.
**Note:** A name, phone number, and country code are required. |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.emailAddress` | **Type:** String
**Description:** The email address of the contact for the address |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.company` | **Type:** String
**Description:** The company name for the address |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.street1` | **Type:** String
**Description:** The first address line |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.street2` | **Type:** String
**Description:** The second address line |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.city` | **Type:** String
**Description:** The name of the city for the address |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.state` | **Type:** String
**Description:** The name of the state for the address |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.postalCode` | **Type:** String
**Description:** A country-appropriate postal code for the address |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for this address |
| `multiParcelShipmentParameters.customsInfo .ultimateConsigneeType` | **Type:** String (enumeration)
**Values:**`direct_consumer`, `government_entity`, `reseller`
**Description:** The type of the ultimate consignee; if no value is sent, it will default to `direct_consumer`. |
| `multiParcelShipmentParameters.customsInfo .aesInternalTransactionNumber` | **Type:** String
**Description:** The number received if the Electronic Export Information (EEI) was filed and has been accepted in the Automated Export System (AES) |
| `multiParcelShipmentParameters.customsInfo .customsItems.productId` | **Type:** String
**Description:** A product ID for the customs item |
| `multiParcelShipmentParameters.customsInfo .customsItems.commodityPartNumber` | **Type:** String
**Description:** The part number or reference number for the product |
| `multiParcelShipmentParameters.customsInfo .customsItems.marksAndNumbers` | **Type:** String
**Description:** Any special marks, codes, and numbers that may identify the package |
| `multiParcelShipmentParameters.customsInfo .customsItems.electronicExportCommodityInformation .exportLicenseInformation.licenseExemptionCode` | **Type:** String
**Description:** The license exemption code, if the license type does not require a license number |
### Example cURL request [Skip link to Example cURL request](https://docs.shipium.com/docs/multi-parcel-shipments\#example-curl-request-1)
This example shows the cURL request.
cURL
### Example request body [Skip link to Example request body](https://docs.shipium.com/docs/multi-parcel-shipments\#example-request-body-1)
This example shows the minimum fields required for the JSON request body.
JSON
```json
{
"currencyCode": "usd",
"generateLabel": true,
"labelParameters": {
"currencyCode": "usd",
"includeLabelImagesInResponse": true,
"labelFormats": [\
"zpl"\
],
"manifest": true
},
"multiParcelShipmentParameters": {
"partnerShipmentId": "myCustomPartnerShipmentId123",
"fulfillmentContext": "fulfillment-context",
"shippedDateTime": "2024-04-10T15:15:14Z",
"orderedDateTime": "2024-04-10T15:15:14Z",
"desiredDeliveryDate": "2024-04-18",
"testMode": true,
"destinationAddress": {
"name": "John Buyer",
"phoneNumber": "2223334444",
"street1": "4 Random St.",
"city": "Toronto",
"state": "ON",
"countryCode": "CA",
"postalCode": "M9B 2J3",
"addressType": "residential"
},
"shipFromAddress": {
"addressType": "commercial",
"city": "Indianapolis",
"phoneNumber": "3177941334",
"state": "IN",
"postalCode": "46241",
"company": "Selling It",
"name": "Ro Drunner",
"street1": "100 Shipium Way",
"street2": "Unit 1",
"countryCode": "US"
},
"customsInfo": {
"taxIdentificationNumber": "12345",
"totalCustomsValue": 54.95,
"totalCustomsValueCurrency": "usd",
"customsDescription": "9 mm steel screws",
"reasonForExport": "sale",
"invoiceDate": "2022-06-13",
"invoiceNumber": "123-abc-456",
"ultimateConsigneeAddress": {
"name": "Wile E. Coyote",
"phoneNumber": "1112223333",
"emailAddress": "wilecoyote@buyit.com",
"street1": "123 Sample St.",
"city": "St. John's",
"state": "NL",
"countryCode": "CA",
"postalCode": "A1A 2H4",
"addressType": "residential"
},
"ultimateConsigneeType": "direct_consumer",
"aesInternalTransactionNumber": "X20220613366903",
"electronicExportInformation": {
"exportDate": "2022-06-15",
"pointOfOrigin": "CO"
},
"customsItems": [\
{\
"customsValue": 18.31,\
"customsValueCurrency": "usd",\
"commodityDescription": "9 mm steel screws",\
"countryOfManufacture": "US",\
"customsWeight": {\
"weight": 4,\
"weightUnit": "lb"\
},\
"quantity": 3,\
"quantityUnitOfMeasurement": "box",\
"harmonizedTariffNumber": "9876543210",\
"productId": "ET-14-4000",\
"commodityPartNumber": "12345",\
"marksAndNumbers": "1 of 1",\
"electronicExportCommodityInformation": {\
"exportType": "domestic",\
"exportInformationCode": "LC",\
"scheduleBInformation": {\
"scheduleBNumber": "6404195500",\
"scheduleBQuantity": 3,\
"scheduleBUnitOfMeasurement": "pack"\
},\
"eccnNumber": "EAR99",\
"exportLicenseInformation": {\
"licenseType": "C33",\
"licenseExemptionCode": "NLR",\
"exportLicense": { // Note: not needed if you have provided a licenseExemptionCode\
"licenseNumber": "123ABC",\
"licenseLineValue": 1000,\
"licenseExpiration": "2025-06-13"\
}\
}\
}\
},\
{\
"customsValue": 18.31,\
"customsValueCurrency": "usd",\
"commodityDescription": "9 mm steel screws",\
"countryOfManufacture": "US",\
"customsWeight": {\
"weight": 4,\
"weightUnit": "lb"\
},\
"quantity": 3,\
"quantityUnitOfMeasurement": "box",\
"harmonizedTariffNumber": "9876543210",\
"productId": "7G-100-0756",\
"commodityPartNumber": "12345",\
"marksAndNumbers": "1 of 1",\
"electronicExportCommodityInformation": {\
"exportType": "domestic",\
"exportInformationCode": "LC",\
"scheduleBInformation": {\
"scheduleBNumber": "6404195500",\
"scheduleBQuantity": 3,\
"scheduleBUnitOfMeasurement": "pack"\
},\
"eccnNumber": "EAR99",\
"exportLicenseInformation": {\
"licenseType": "C33",\
"licenseExemptionCode": "NLR",\
"exportLicense": { // Note: not needed if you have provided a licenseExemptionCode\
"licenseNumber": "123ABC",\
"licenseLineValue": 1000,\
"licenseExpiration": "2025-06-13"\
}\
}\
}\
}\
]
},
"packages": [\
{\
"orderItemQuantities": [\
{\
"shipiumOrderId": 123,\
"productId": "ET-14-4000",\
"quantity": 2,\
"productDetails": [],\
"hazmat": false\
}\
],\
"packagingType": {\
"linearDimensions": {\
"height": 10,\
"length": 13,\
"linearUnit": "in",\
"width": 12\
},\
"packagingMaterial": "box",\
"packagingSizeName": "13x12x10 box",\
"packagingWeight": {\
"weight": 50,\
"weightUnit": "lb"\
}\
},\
"totalWeight": {\
"weight": 50,\
"weightUnit": "lb"\
},\
"packageReferenceIdentifier": "package1",\
"partnerProvidedPackageId": "13_in_box"\
},\
{\
"orderItemQuantities": [\
{\
"shipiumOrderId": 123,\
"productId": "ET-14-4000",\
"quantity": 2,\
"productDetails": [],\
"hazmat": false\
}\
],\
"packagingType": {\
"linearDimensions": {\
"height": 11,\
"length": 13,\
"linearUnit": "in",\
"width": 12\
},\
"packagingMaterial": "box",\
"packagingSizeName": "13x12x10 box",\
"packagingWeight": {\
"weight": 50,\
"weightUnit": "lb"\
}\
},\
"packageReferenceIdentifier": "package2",\
"totalWeight": {\
"weight": 50,\
"weightUnit": "lb"\
}\
}\
]
}
}
```
### Example response body [Skip link to Example response body](https://docs.shipium.com/docs/multi-parcel-shipments\#example-response-body-1)
JSON
# Resources [Skip link to Resources](https://docs.shipium.com/docs/multi-parcel-shipments\#resources)
Your Shipium team member is available to help along the way. However, you might find these resources helpful:
- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)
# FAQ [Skip link to FAQ](https://docs.shipium.com/docs/multi-parcel-shipments\#faq)
**Q:** Why is `actualWeight` different from my total measured weight?
**A:** The `actualWeight` field represents rounded weight, which applies carrier-specific rounding rules to the physical weight. This is expected behavior for multi-parcel shipments and ensures accurate carrier rating for carriers that require weight rounding.
**Q:** Which weight determines my multi-parcel shipping cost?
**A:** The `billableWeight` field shows the weight used for cost calculation. This is determined by:
1. Taking the greater of: rounded weight (for carriers that use rounding) OR physical weight (for carriers that don't) vs. dimensional weight
2. Rounding up to the next increment in the carrier's rate table (ceiling)
For example, if the greater weight is 24.7 lbs, the billable weight will be 25 lbs if the carrier's rate sheet increments by whole pounds.
**Q:** Why is my billable weight higher than both my calculated weights?
**A:** Billable weight rounds up to the carrier's rate table increments. If your greater weight (physical/rounded or dimensional) is 24.7 lbs, it rounds up to 25 lbs because carrier rate sheets don't have fractional weight tiers. This is standard across all carriers.
**Q:** Why is my multi-parcel shipment more expensive than expected?
**A:** Compare the `physicalWeight` (or `actualWeight`) with `dimWeight` in the API response. If dimensional weight is higher, your packages are taking up more space relative to their weight, which increases costs. Additionally, check if you're close to a rate tier boundary; even small weight increases can push you to the next pricing tier.
**Q:** How do I minimize multi-parcel shipping costs?
**A:** Focus on three areas:
1. **Dimensional weight optimization.** Use appropriately sized packaging, minimize empty space, and consolidate items efficiently.
2. **Weight distribution.** Distribute weight evenly across packages where possible to avoid hitting higher rate tiers.
3. **Rate tier awareness.** If your total weight is 24.7 lbs (billing at 25 lbs), reducing to 24.0 lbs or below drops you to the 24-lb rate tier.
Updated 4 months ago
* * *
Did this page help you?
Yes
No
Copy Page