Shipment: Single Parcel and Multi-Parcel Support

Overview

The Create Shipment API has been enhanced to support both the existing single-parcel request structure and a new parcels-based request structure. This enhancement is introduced to preserve backward compatibility for existing integrations while enabling a more flexible and scalable request model for new implementations.

Until now, Create Shipment supported parcel data using the root-level parcel and parcelType fields. With this enhancement, the API also supports a new parcels array structure. This new structure can be used for creating a shipment with a single parcel as well as a shipment with multiple parcels.

As a result, the API now supports three valid request patterns for domestic shipment creation:

the existing single-parcel structure using parcel and parcelType
the new single-parcel structure using the parcels array with one parcel
the new multi-parcel structure using the parcels array with multiple parcels

This approach allows existing users to continue using their current request format without change, while giving new users a single extensible structure for both single-parcel and multi-parcel shipment creation.

What is supported now

The Rate Shipment and Create Shipment APIs now support the following request structures.

Existing structure

The existing request format continues to support shipment creation using the following fields at the root level:

parcel
parcelType

This is the legacy single-parcel structure.

New structure

The new request format supports shipment creation using:

parcels

The parcels field is an array. Each item in the array represents one parcel entry and contains:

parcel
parcelType
specialServices - optional
references - optional
items - optional (either pass the object or previously defined customsProductId)
Read: How to create Customs Product Identifier

"items": 
 [
    {
        "itemId": "sku1",
        "description": "Book",
        "hSTariffCode": "490191",
        "originCountryCode": "US",
        "originStateProvince": "TX",
        "quantity": 2,
        "unitPrice": 10,
        "weightUnit": "GM",
        "weight": 80,
        "orderNumber": "22"
    },
    {
        "customsProductId": "cp00000922010"
    }
  ]

This means the same parcels array can now be used in the following ways:

to create a shipment with one parcel
to create a shipment with multiple parcels single label
to create a shipment with multiple parcels split labels (using query parameter splitContent: true)

How to choose between the two structures

If you are already integrated with the existing Create Shipment request format and are sending parcel and parcelType, you can continue using that structure without any change.

If you are building a new integration, the recommended approach is to use the parcels array structure. It provides a single consistent model for both single-parcel and multi-parcel shipment creation and is better suited for future extensibility.

The main distinction is simple:

use parcel and parcelType if you want to continue with the existing legacy format
use parcels if you want to adopt the new structure

Existing single-parcel request structure

The existing structure represents parcel information directly at the root level of the request body.

In this model:

parcel contains parcel dimensions, weight, and related details
parcelType identifies the parcel type for that shipment

This format remains fully supported for domestic shipment creation.

API Operations

The APIs provide the following operations:

Operation	Method	Resource Path
Rate Shipment	POST	/api/v2/rates
Create Shipment	POST	/api/v2/shipments

Base URL for US Region

Sandbox Server url: "https://api-sandbox.sendpro360.pitneybowes.com/shipping"
Production Server url: "https://api.sendpro360.pitneybowes.com/shipping"

Base URL for CA Region

Sandbox Server url: "https://api-ppd.shipping360.pitneybowes.com/ca/shipping"
Production Server url: "https://api.shipping360.pitneybowes.com/ca/shipping"

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

Rate Shipment (By Carrier) sample Request Payloads

  {
      "fromAddress": {
          "addressLine1": "24182 Kathy Ave",
          "cityTown": "Lake Forest",
          "countryCode": "US",
          "name": "Paul Wright",
          "phone": "203-555-1213",
          "postalCode": "92630-1827",
          "stateProvince": "CA"
      },
      "toAddress": {
          "addressLine1": "55 Pharr Rd NW, Apt E104",
          "cityTown": "Atlanta",
          "countryCode": "US",
          "name": "Paul Wright",
          "phone": "203-555-1213",
          "postalCode": "30305-2151",
          "stateProvince": "GA"
      },
      "altReturnAddress": {
          "addressLine1": "47 W 13th St",
          "cityTown": "New York",
          "company": "ABC Company",
          "countryCode": "US",
          "email": "sender@email.com",
          "name": "altReturnAddress Name",
          "phone": "323 555-1212",
          "postalCode": "10011",
          "residential": false,
          "stateProvince": "NY"
      },
      "parcel": {
          "length": 2,
          "width": 0.5,
          "height": 1,
          "dimUnit": "IN",
          "weightUnit": "OZ",
          "weight": 2,
          "packageValue": 2
      },
      "parcelType": "PKG",
      "rateShopBy": "carrier",
      "byCarrier": {
          "carrierAccountId": "{{ups_carrier_id}}",
          "carrier": "UPS",
          "service": "NDA"
      },

      "specialServices": [
          {
              "specialServiceId": "ADD_HDL"
          },
          {
              "specialServiceId": "ins",
              "inputParameters": [
                  {
                      "name": "INPUT_VALUE",
                      "value": "101"
                  }
              ]
          },
          {
              "specialServiceId": "DIRECT"
          }
      ]
}

Rate Shipment (By Carrier) Response Payloads

{
  "fromAddress": {
      "addressLine1": "24182 Kathy Ave",
      "cityTown": "Lake Forest",
      "countryCode": "US",
      "name": "Paul Wright",
      "phone": "203-555-1213",
      "postalCode": "92630-1827",
      "residential": false,
      "stateProvince": "CA"
  },
  "toAddress": {
      "addressLine1": "55 Pharr Rd NW, Apt E104",
      "cityTown": "Atlanta",
      "countryCode": "US",
      "name": "Paul Wright",
      "phone": "203-555-1213",
      "postalCode": "30305-2151",
      "residential": false,
      "stateProvince": "GA"
  },
  "rate": [
      {
          "baseCharge": 102.45,
          "carrier": "ups",
          "carrierAccount": "vO396rorMdxZ8k1",
          "currencyCode": "USD",
          "deliveryCommitment": {
              "estimatedDeliveryDateTime": "2026-04-27 10:30:00",
              "guarantee": "FULL",
              "maxEstimatedNumberOfDays": "1",
              "minEstimatedNumberOfDays": "1"
          },
          "parcelType": "PKG",
          "rateTypeId": "COMMERCIAL",
          "serviceId": "NDA",
          "specialServices": [
              {
                  "specialServiceId": "ADD_HDL",
                  "fee": 33.75
              },
              {
                  "specialServiceId": "ins",
                  "inputParameters": [
                      {
                          "name": "INPUT_VALUE",
                          "value": "101"
                      }
                  ],
                  "fee": 0
              },
              {
                  "specialServiceId": "DIRECT",
                  "fee": 2
              }
          ],
          "surcharges": [
              {
                  "fee": 7,
                  "name": "RESIDENTIAL"
              },
              {
                  "fee": 43.32,
                  "name": "FUEL"
              }
          ],
          "totalCarrierCharge": 151.24,
          "isHazmat": true,
          "publishedTotalCarrierCharge": 186.52
      }
  ],
  "shipmentOptions": {
      "billingWeight": "16.0"
  },
  "parcel": {
      "length": 2,
      "height": 1,
      "width": 0.5,
      "dimUnit": "IN",
      "weightUnit": "OZ",
      "weight": 2,
      "packageValue": 2
  }
}

Create Shipment (By Carrier) sample Request Payloads

  {
      "toAddress": {
          "addressLine1": "55 Pharr Rd NW, Apt E104",
          "cityTown": "Atlanta",
          "countryCode": "US",
          "name": "Paul Wright",
          "phone": "203-555-1213",
          "postalCode": "30305-2151",
          "stateProvince": "GA"
      },
      "fromAddress": {
          "addressLine1": "24182 Kathy Ave",
          "cityTown": "Lake Forest",
          "countryCode": "US",
          "name": "Paul Wright",
          "phone": "203-555-1213",
          "postalCode": "92630-1827",
          "stateProvince": "CA"
      },
      "soldToAddress": {
          "addressLine1": "70 Hanlan RD",
          "addressLine2": "Suite 101",
          "addressLine3": "Near central market",
          "company": "ABC Company",
          "name": "John Doe",
          "phone": "905-555-1234",
          "email": "billing@abccompany.com",
          "residential": false,
          "cityTown": "Woodbridge",
          "stateProvince": "ON",
          "postalCode": "L4L 3P6",
          "countryCode": "CA",
          "taxId": "string",
          "taxIdType": "EIN"
      },
      "altReturnAddress": {
          "addressLine1": "24182 Kathy Ave",
          "cityTown": "Lake Forest",
          "countryCode": "US",
          "name": "Paul Wright",
          "phone": "203-555-1213",
          "postalCode": "92630-1827",
          "stateProvince": "CA"
      },
      "additionalAddresses": [
          {
              "address": {
                  "residential": false,
                  "phone": "732-443-1007",
                  "countryCode": "US",
                  "company": "ABC Company",
                  "postalCode": "08810-1411",
                  "cityTown": "DAYTON",
                  "name": "Warehouse Manager",
                  "stateProvince": "NJ",
                  "addressLine1": "2270 US HIGHWAY 130"
              },
              "addressType": "SHIPPER"
          }
      ],
      "parcel": {
          "length": 2,
          "width": 1,
          "height": 1,
          "dimUnit": "IN",
          "weightUnit": "OZ",
          "weight": 2,
          "packageValue": 2
      },
      "parcelType": "PKG",
      "rateShopBy": "carrier",
      "byCarrier": {
          "carrierAccountId": "{{ups_carrier_id}}",
          "carrier": "UPS",
          "service": "NDA"
      },
      "shipmentOptions": {
          "addToManifest": true,
          "shipperID": "1234567890"
      },
      "specialServices": [
          {
              "inputParameters": [
                  {
                      "name": "INPUT_VALUE",
                      "value": "100"
                  }
              ],
              "specialserviceId": "Ins"
          }
      ],
      "metadata": [
          {
              "name": "costAccountName",
              "value": "costAccountName"
          },
          {
              "name": "costAccountId",
              "value": "costAccountId"
          },
          {
              "name": "costAccountCode",
              "value": "Code"
          },
          {
              "name": "accountCode",
              "value": "code"
          },
          {
              "name": "companyCode",
              "value": "code"
          }
      ],
      "carrierPayments": [
          {
              "accountNumber": "602684342",
              "countryCode": "US",
              "postalCode": "30305",
              "party": "BILL_RECEIVER",
              "typeOfCharge": "DUTIES_AND_TAXES"
          }
      ],
      "references": {
          "reference1": "123456",
          "reference2": "SendTech",
          "reference3": "98437",
          "reference4": "UPS Shipping",
          "poNumber": "R2W 2H2",
          "department": "Name department",
          "additionalReference1": "612987641",
          "additionalReference2": "989",
          "shippingNotes": "Handle with care",
          "ShipperReference": "REF123456789",
          "transportationReference": "TRANSREF987654321"
      },
      "labelSize": "DOC_4X6",
      "labelType": "SHIPPING_LABEL",
      "labelFormat": "ZPL2",
      "printerAliasName": "test",
      "dateOfShipment": "{{todayDate}}",
      "deliveryOption": {
          "deliverBy": "{{tomorrowDate}}",
          "useBestNextDate": false
      }
}

Create Shipment (By Carrier) sample Response Payloads

  {
      "correlationId": "de221671ff2c4a84891604c32cdf8221",
      "shipmentId": "UPS2202640808297347",
      "carrierAccountId": "vO396rorMdxZ8k1",
      "parcelTrackingNumber": "UPS2202640808297347",
      "labelLayout": [
          {
              "contentType": "BASE64",
              "contents": "Cl5YQQ0KXkxSTg0KXk1OWQ0KXk1GTixODQpeTEgxMCwxMg0KXk1DWQ0KXlBPSQ0KXlBXODEyDQpeQ0kyNw0KXkZPMTUsN15BME4sMjAsMjReRlZQQVVMIFdSSUdIVF5GUw0KXkZPMTUsMjdeQTBOLDIwLDI0XkZWMjAzLTU1NS0xMjEzXkZTDQpeRk8xNSw0N15BME4sMjAsMjReRlZQQVVMIFdSSUdIVF5GUw0KXkZPMTUsNjdeQTBOLDIwLDI0XkZWMjQxODIgS0FUSFkgQVZFXkZTDQpeRk8xNSw4N15BME4sMjAsMjReRlZMQUtFIEZPUkVTVCAgQ0EgOTI2MzAtMTgyN15GUw0KXkZPMTUsMTQyXkEwTiwyOCwzMl5GVlNISVAgVE86IF5GUw0KXkZPNjEsMTY2XkEwTiwyOCwzMl5GVlBBVUwgV1JJR0hUXkZTDQpeRk82MSwxOTReQTBOLDI4LDMyXkZWMjAzLTU1NS0xMjEzXkZTDQpeRk82MSwyMjJeQTBOLDI4LDMyXkZWUEFVTCBXUklHSFReRlMNCl5GTzYxLDI1MV...............................0KXkRODQpeWFoNCg==",
              "fileFormat": "ZPL2",
              "size": "DOC_4X6",
              "type": "SHIPPING_LABEL"
          }
      ],
      "parcel": {
          "length": 2,
          "height": 1,
          "width": 1,
          "dimUnit": "IN",
          "weightUnit": "OZ",
          "weight": 2,
          "packageValue": 2
      },
      "rate": {
          "baseCharge": 102.45,
          "carrier": "UPS",
          "currencyCode": "USD",
          "deliveryCommitment": {
              "estimatedDeliveryDateTime": "2026-04-27 12:00:00",
              "guarantee": "FULL",
              "maxEstimatedNumberOfDays": "1",
              "minEstimatedNumberOfDays": "1"
          },
          "inductionPostalCode": "92630",
          "parcelType": "PKG",
          "rateTypeId": "COMMERCIAL",
          "serviceId": "NDA",
          "specialServices": [
              {
                  "specialServiceId": "Ins",
                  "inputParameters": [
                      {
                          "name": "INPUT_VALUE",
                          "value": "100"
                      }
                  ],
                  "fee": 0
              }
          ],
          "surcharges": [
              {
                  "fee": 7,
                  "name": "RESIDENTIAL"
              },
              {
                  "fee": 33.11,
                  "name": "FUEL"
              }
          ],
          "totalCarrierCharge": 141.13,
          "isHazmat": false,
          "publishedTotalCarrierCharge": 142.56
      },
      "references": {
          "reference1": "123456",
          "reference2": "SendTech",
          "reference3": "98437",
          "reference4": "UPS Shipping",
          "department": "Name department",
          "poNumber": "R2W 2H2",
          "additionalReference1": "612987641",
          "additionalReference2": "989",
          "shippingNotes": "Handle with care",
          "ShipperReference": "REF123456789",
          "transportationReference": "TRANSREF987654321"
      },
      "print": {
          "status": "error",
          "jobId": "AE95zYxKW9JKGEQ",
      },
      "fromAddress": {
          "addressLine1": "24182 Kathy Ave",
          "cityTown": "Lake Forest",
          "company": "Paul Wright",
          "countryCode": "US",
          "name": "Paul Wright",
          "phone": "203-555-1213",
          "postalCode": "92630-1827",
          "residential": true,
          "stateProvince": "CA",
          "status": "VALIDATED_AND_NOT_CHANGED"
      },
      "toAddress": {
          "addressLine1": "55 Pharr Rd NW, Apt E104",
          "cityTown": "Atlanta",
          "company": "Paul Wright",
          "countryCode": "US",
          "name": "Paul Wright",
          "phone": "203-555-1213",
          "postalCode": "30305-2151",
          "residential": true,
          "stateProvince": "GA",
          "status": "VALIDATED_AND_NOT_CHANGED"
      },
      "altReturnAddress": {
          "addressLine1": "24182 Kathy Ave",
          "cityTown": "Lake Forest",
          "countryCode": "US",
          "name": "Paul Wright",
          "phone": "203-555-1213",
          "postalCode": "92630-1827",
          "residential": false,
          "stateProvince": "CA"
      },
      "shipmentOptions": {
          "billingWeight": "16.0"
      },
      "soldToAddress": {
          "addressLine1": "70 Hanlan RD",
          "addressLine2": "Suite 101",
          "addressLine3": "Near central market",
          "cityTown": "Woodbridge",
          "company": "ABC Company",
          "countryCode": "CA",
          "email": "billing@abccompany.com",
          "name": "John Doe",
          "phone": "905-555-1234",
          "postalCode": "L4L 3P6",
          "residential": false,
          "stateProvince": "ON",
          "taxId": "string",
          "taxIdType": "EIN"
      },
      "carrierPayments": [
          {
              "accountNumber": "602684342",
              "countryCode": "US",
              "party": "BILL_RECEIVER",
              "postalCode": "30305",
              "typeOfCharge": "DUTIES_AND_TAXES"
          }
      ],
      "additionalAddresses": [
          {
              "address": {
                  "addressLine1": "2270 US HIGHWAY 130",
                  "cityTown": "DAYTON",
                  "company": "ABC Company",
                  "countryCode": "US",
                  "name": "Warehouse Manager",
                  "phone": "732-443-1007",
                  "postalCode": "08810-1411",
                  "residential": false,
                  "stateProvince": "NJ"
              },
              "addressType": "SHIPPER"
          }
      ]
}

Key behavior and rules

A request must use only one parcel structure. Do not include both parcel and parcels in the same request.
The parcels array can be used for both single-parcel and multi-parcel shipments. There is no restriction on using it only for multiple parcels.
Shipment-level specialServices continue to work as before and apply to the entire shipment. In addition, parcel-level specialServices can be defined within each parcel item when using the parcels structure.
All other fields in the Create Shipment request remain unchanged and behave consistently across both structures.