Multipiece Shipment

The operation creates Multipiece Shipments. Shipments with multiple parcels sent to the same destination can be grouped together in a multipiece shipment.

  • UPS, FedEx, DHL Express, Suprmsys, Purolator, Apple Express and Tforce Mile are supported for Multipiece Shipments.

  • Maximum Parcels Allowed per Carrier:

    • DHL: 75
    • FedEx: 40
    • UPS: 50
    • Purolator: 100
    • Apple Express: 75
    • Tforce Mile: 75

  • For UPS- multipiece shipment with Envelopes (having parcel Type as LTR) is not supported.

  • For FedEx Multipiece, all parcels must be of same packaging type while creating multipiece shipment

  • USPS does not support multi-piece parcels in a single shipment at this time.

SecuritybearerAuth
Request
query Parameters
includeDeliveryCommitment
string
Default: true

When set to true (default), the response includes delivery commitment information. Set to false to exclude delivery commitment details from the response.

splitContent
boolean
Default: false

Include this parameter only if you want to generate separate labels for each parcel in a multi-piece shipment. As of now, individual parcel labels supported for carriers FedEx and UPS.

header Parameters
X-PB-Developer-Partner-Id
string

This is the Developer Partner ID. When the developer is the only partner, this field is not required.

X-PB-LocationId
string

The X-PB-LocationId header identifies the enterprise, developer, or partner location under which a shipment is processed and billed. If the header is not provided, the system defaults to the enterprise-level location that was created during developer account onboarding. This default location is automatically used for shipment processing and billing.

Requirement Rules

  • The X-PB-LocationId header is optional when the shipment origin country code matches the enterprise's default address country code.
  • The X-PB-LocationId header is required when the shipment origin country code differs from the enterprise's default address country code.
  • If the header is required but not provided, the API will return a validation error "invalid origin countryCode".
Request Body schema: application/json
One of:
size
required
string

Defines the label size of the Shipment, e.g., Shipping Label having Doc Size (4' X 8' or 8.5' X 11'). It supports the document sizes as per the eligible carrier size support.

Enum: "DOC_8X11" "DOC_4X8" "DOC_4X6"
format
string

Defines the type of the multipiece shipment label that is printed.
PDF supports content type URL.
ZPL2 supports content type BASE64.

Enum: "PDF" "ZPL2"
type
string

Defines the type of the Shipment, e.g., Shipping Label.

Value: "SHIPPING_LABEL"
contentType
string

Specifies how the label content is encoded.
URL is supported for PDF .
BASE64 is supported for ZPL2.

Enum: "URL" "BASE64"
required
object
carrierAccountId
required
string

A unique identifier associated with the Carrier account used by client users during shipment process.

serviceId
required
string

-A unique identifier given to the carrier-specific service. This is required for creating a shipment, while it is optional for rating a parcel.

object

Additional options for the shipment.

Array of FedEx Carrier Payment (object) or UPS Carrier Payment (object) or DHL Express Carrier Payment (object) or Purolator Carrier Payment (object) (carrierPayments)

Defines how carrier charges are billed to a third party. Use this field to specify account and charge type details for transportation and/or duties and taxes. This field is optional and currently supported for FedEx, UPS, DHL Express and Purolator.

  • If no party (who will pay for TRANSPORTATION_CHARGES or duties and taxes) is explicitly specified during shipment creation, the charges will automatically default to the sender (shipper). To direct charges to a different party, the appropriate bill-to details must be provided in the request.
Array of objects

An array containing custom metadata for the shipment.

required
Array of objects

Details of each parcel in the shipment.

required
object

The recipient's address information.

object

This is an optional field. if a package shipped from Location_A to Location_B needs to return to Location_C. The alternate address will be printed on the label. Use this object to specify a return address different from the fromAddress. Supported by FedEx, UPS and Purolator.

Array of objects (additionalAddresses)

A list of additional addresses associated with the shipment.

  • Each object includes an address and its designated type, such as BROKER or other parties involved in customs or shipping processes.
  • Additional address could be domestic or International both.
Responses
200

The Multipiece Shipment created successfully.

400

Invalid request.

401

The request could not be authorized.

500

The request could not be completed due to an internal error.

post/api/v1/multipiece/shipments
Request samples
application/json
{
  • "size": "DOC_4X8",
  • "format": "PDF",
  • "type": "SHIPPING_LABEL",
  • "contentType": "URL",
  • "fromAddress": {
    },
  • "carrierAccountId": "4J67bLB62BG",
  • "serviceId": "NDA",
  • "shipmentOptions": {
    },
  • "carrierPayments": [
    ],
  • "metadata": [
    ],
  • "multiPieceParcels": [
    ],
  • "toAddress": {
    },
  • "altReturnAddress": {
    },
  • "additionalAddresses": [
    ]
}
Response samples
application/json
{
  • "correlationId": "00da5e928af44bcc9e5c092163e036f9",
  • "labelLayout": [],
  • "fromAddress": {
    },
  • "multiPieceRates": [
    ],
  • "parcelTrackingNumber": "UPS2200619919802570P0",
  • "shipmentId": "UPS2200619919802570",
  • "shipmentOptions": {
    },
  • "carrierPayments": [
    ],
  • "toAddress": {
    },
  • "altReturnAddress": {
    },
  • "additionalAddresses": [
    ]
}