Create 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:

  1. the existing single-parcel structure using parcel and parcelType
  2. the new single-parcel structure using the parcels array with one parcel
  3. 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 an Create Shipment APIs now supports 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

Copy
Copied
"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:

OperationMethodResource Path
Rate ShipmentPOST/api/v2/rates
Create ShipmentPOST/api/v2/shipments

Base URL for US Region

Base URL for CA Region

Header:

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

Single ParcelSingle Parcel using ParcelsMulti-Parcel
Copy
Copied
{
    "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"
        }
    ]
}
Copy
Copied
{
    "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"
    },
    "parcels": [
        {
            "parcel": {
                "length": 2,
                "width": 1,
                "height": 1,
                "dimUnit": "IN",
                "weightUnit": "OZ",
                "weight": 2
            },
            "parcelType": "PKG",
            "specialServices": [
                {
                    "inputParameters": [
                        {
                            "name": "INPUT_VALUE",
                            "value": "100"
                        }
                    ],
                    "specialserviceId": "Ins"
                }
            ]
        }
    ],
    "rateShopBy": "carrier",
    "byCarrier": {
        "carrierAccountId": "{{ups_carrier_id}}",
        "carrier": "UPS",
        "service": "NDA"
    }
}
Copy
Copied
{
  "fromAddress": {
    "name": "Sender Name",
    "addressLine1": "1600 Amphitheatre Parkway",
    "addressLine2": "near abc street",
    "addressLine3": "near xyz street",
    "company": "PB",
    "email": "testuser@gmail.com",
    "phone": "6502530000",
    "cityTown": "Mountain View",
    "stateProvince": "CA",
    "postalCode": "94043",
    "inductionPostalCode": "06905",
    "countryCode": "US",
    "residential": true
  },
  "toAddress": {
    "name": "Recipient Name",
    "addressLine1": "350 Fifth Avenue",
    "addressLine2": "near abc street",
    "addressLine3": "near xyz street",
    "cityTown": "New York",
    "stateProvince": "NY",
    "postalCode": "10118",
    "countryCode": "US",
    "company": "PB",
    "phone": "2127363100",
    "email": "recipient@gmail.com",
    "residential": true,
    "isPOBox": true
    },
    "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"
    },
    "parcels": [
        {
            "parcel": {
                "length": 2,
                "width": 1,
                "height": 1,
                "dimUnit": "IN",
                "weightUnit": "OZ",
                "weight": 2
            },
            "parcelType": "PKG",
            "specialServices": [
                {
                "inputParameters": [
                    {
                    "name": "INPUT_VALUE",
                    "value": "100"
                    }
                ],
                "specialserviceId": "Ins"
                }
          ],

        },
        {
            "parcel": {
                "length": 5,
                "width": 4,
                "height": 3,
                "dimUnit": "IN",
                "weightUnit": "OZ",
                "weight": 8
            },
            "parcelType": "PKG"
        }
    ],
    "rateShopBy": "carrier",
    "byCarrier": {
        "carrierAccountId": "{{ups_carrier_id}}",
        "carrier": "UPS",
        "service": "NDA"
    }
}

Rate Shipment (By Carrier) Rasponse Payloads

Single ParcelSingle Parcel using ParcelsMulti-Parcel
Copy
Copied
{
    "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
    }
}
Copy
Copied
{
    "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"
    },
    "shipmentOptions": {
        "billingWeight": "16.0"
    },
    "rates": [
        {
            "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": "Ins",
                        "inputParameters": [
                            {
                                "name": "INPUT_VALUE",
                                "value": "100"
                            }
                        ],
                        "fee": 0
                    }
                ],
                "surcharges": [
                    {
                        "fee": 7,
                        "name": "RESIDENTIAL"
                    },
                    {
                        "fee": 33.11,
                        "name": "FUEL"
                    }
                ],
                "totalCarrierCharge": 141.13,
                "isHazmat": true,
                "publishedTotalCarrierCharge": 142.56
            },
            "parcels": [
                {
                    "parcel": {
                        "length": 2,
                        "height": 1,
                        "width": 1,
                        "dimUnit": "IN",
                        "weightUnit": "OZ",
                        "weight": 2
                    },
                    "parcelRate": {
                        "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": "Ins",
                                "inputParameters": [
                                    {
                                        "name": "INPUT_VALUE",
                                        "value": "100"
                                    }
                                ],
                                "fee": 0
                            }
                        ],
                        "surcharges": [
                            {
                                "fee": 7,
                                "name": "RESIDENTIAL"
                            },
                            {
                                "fee": 33.11,
                                "name": "FUEL"
                            }
                        ],
                        "totalCarrierCharge": 141.13,
                        "isHazmat": true,
                        "publishedTotalCarrierCharge": 142.56
                    }
                }
            ]
        }
    ]
}
Copy
Copied
{
  "fromAddress": {
    "name": "Sender Name",
    "addressLine1": "1600 Amphitheatre Parkway",
    "addressLine2": "near abc street",
    "addressLine3": "near xyz street",
    "company": "PB",
    "email": "testuser@gmail.com",
    "phone": "6502530000",
    "cityTown": "Mountain View",
    "stateProvince": "CA",
    "postalCode": "94043",
    "inductionPostalCode": "06905",
    "countryCode": "US",
    "residential": true
  },
  "toAddress": {
    "name": "Recipient Name",
    "addressLine1": "350 Fifth Avenue",
    "addressLine2": "near abc street",
    "addressLine3": "near xyz street",
    "cityTown": "New York",
    "stateProvince": "NY",
    "postalCode": "10118",
    "countryCode": "US",
    "company": "PB",
    "phone": "2127363100",
    "email": "recipient@gmail.com",
    "residential": true,
    "isPOBox": true
  },
    "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"
    },
    "shipmentOptions": {},
    "rates": [
        {
            "rate": {
                "carrier": "UPS",
                "currencyCode": "USD",
                "deliveryCommitment": {
                    "estimatedDeliveryDateTime": "2026-04-27 10:30:00",
                    "guarantee": "FULL",
                    "maxEstimatedNumberOfDays": "1",
                    "minEstimatedNumberOfDays": "1"
                },
                "rateTypeId": "COMMERCIAL",
                "serviceId": "NDA",
                "surcharges": [
                    {
                        "fee": 14,
                        "name": "RESIDENTIAL"
                    }
                ],
                "totalCarrierCharge": 282.27,
                "isHazmat": false
            },
            "parcels": [
                {
                    "parcelType": "PKG",
                    "parcel": {
                        "length": 2,
                        "height": 1,
                        "width": 1,
                        "dimUnit": "IN",
                        "weightUnit": "OZ",
                        "weight": 2
                    },
                    "parcelRate": {
                        "baseCharge": 102.45,
                        "deliveryCommitment": {
                            "estimatedDeliveryDateTime": "2026-04-27 10:30:00",
                            "guarantee": "FULL",
                            "maxEstimatedNumberOfDays": "1",
                            "minEstimatedNumberOfDays": "1"
                        },
                        "surcharges": [
                            {
                                "fee": 33.11,
                                "name": "FUEL"
                            }
                        ],
                        "isHazmat": false
                    },
                    "specialServices": [
                        {
                            "specialServiceId": "Ins",
                            "inputParameters": [
                                {
                                    "name": "INPUT_VALUE",
                                    "value": "100"
                                }
                            ],
                            "fee": 0
                        }
                    ]
                },
                {
                    "parcelType": "PKG",
                    "parcel": {
                        "length": 5,
                        "height": 3,
                        "width": 4,
                        "dimUnit": "IN",
                        "weightUnit": "OZ",
                        "weight": 8
                    },
                    "parcelRate": {
                        "baseCharge": 102.45,
                        "deliveryCommitment": {
                            "estimatedDeliveryDateTime": "2026-04-27 10:30:00",
                            "guarantee": "FULL",
                            "maxEstimatedNumberOfDays": "1",
                            "minEstimatedNumberOfDays": "1"
                        },
                        "surcharges": [
                            {
                                "fee": 33.11,
                                "name": "FUEL"
                            }
                        ],
                        "isHazmat": false
                    }
                }
            ]
        }
    ]
}

Create Shipment (By Carrier) sample Request Payloads

Single ParcelSingle Parcel using ParcelsMulti Parcel
Copy
Copied
{
    "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"
    },
    "labelSize": "DOC_4X6",
    "labelType": "SHIPPING_LABEL",
    "labelFormat": "ZPL2",
    "printerAliasName": "test",
    "dateOfShipment": "{{todayDate}}",
    "deliveryOption": {
        "deliverBy": "{{tomorrowDate}}",
        "useBestNextDate": false
    }
}
Copy
Copied
{
    "fromAddress": {
        "addressLine1": "638 Manitoba Ave1",
        "addressLine2": "638 Manitoba Ave2",
        "addressLine3": "638 Manitoba Ave3",
        "cityTown": "Winnipeg",
        "countryCode": "CA",
        "name": "Paul Wright",
        "company": "PB & Company",
        "phone": "203-555-1213",
        "postalCode": "R2W 2H2",
        "stateProvince": "MB"
    },
    "toAddress": {
        "addressLine1": "947 Hammarskjold Dr1",
        "addressLine2": "947 Hammarskjold Dr2",
        "addressLine3": "947 Hammarskjold Dr3",
        "cityTown": "Burnaby",
        "countryCode": "CA",
        "name": "Paul Wright",
        "company": "QA & Company",
        "phone": "604-320-7572",
        "postalCode": "V5B 3C9",
        "stateProvince": "BC"
    },
    "altReturnAddress": {
        "company": "ABC Company",
        "name": "Rufous Sirius Canid",
        "phone": "323 555-1212",
        "email": "rs.canid@gmail.com",
        "addressLine1": "2976 Sherbrooke Ouest1",
        "addressLine2": "2976 Sherbrooke Ouest2",
        "addressLine3": "2976 Sherbrooke Ouest3",
        "cityTown": "Montreal",
        "stateProvince": "QC",
        "postalCode": "H4A1H3",
        "countryCode": "CA"
    },
    "additionalAddresses": [
        {
            "address": {
                "residential": false,
                "phone": "732-443-1007",
                "countryCode": "US",
                "company": "PB&Cmpany/Co.",
                "postalCode": "08810-1411",
                "cityTown": "DAYTON",
                "name": "Warehouse Manager",
                "stateProvince": "NJ",
                "addressLine1": "2270 US HIGHWAY 130"
            },
            "addressType": "THIRD_PARTY"
        }
    ],
    "soldToAddress": {
        "addressLine1": "47 W 13th St",
        "cityTown": "New York",
        "company": "ABC Company",
        "countryCode": "US",
        "email": "soldTo@email.com",
        "name": "soldToAddress Name",
        "phone": "323 555-1212",
        "postalCode": "10011",
        "residential": false,
        "stateProvince": "NY"
    },
    "parcels": [
        {
            "parcel": {
                "length": 10,
                "width": 10,
                "height": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 2000
            },
            "parcelType": "PKG",
            "specialServices": [
                {
                    "specialServiceId": "ADD_HDL"
                }
            ],
            "items": [
                {
                    "itemId": "sku1",
                    "description": "Book",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "TX",
                    "quantity": 2,
                    "unitPrice": 10,
                    "weightUnit": "GM",
                    "weight": 80,
                    "orderNumber": "22"
                },
                {
                    "itemId": "sku2",
                    "description": "Geometry",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "MB",
                    "quantity": 1,
                    "unitPrice": 101,
                    "weightUnit": "GM",
                    "weight": 432,
                    "orderNumber": "23"
                }
            ],
            "references": {
                "reference1": "#43 | FD000689 | 41798000200000",
                "reference2": "ref2",
                "reference3": "ref3",
                "reference4": "ref4"
            }
        },
        {
            "parcel": {
                "length": 10,
                "width": 10,
                "height": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 1500
            },
            "parcelType": "PKG",
            "items": [
                {
                    "itemId": "sku3",
                    "description": "Jeans",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "NY",
                    "quantity": 2,
                    "unitPrice": 40,
                    "weightUnit": "GM",
                    "weight": 150,
                    "orderNumber": "22"
                },
                {
                    "itemId": "sku4",
                    "description": "Shoes",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "ON",
                    "quantity": 2,
                    "unitPrice": 50,
                    "weightUnit": "GM",
                    "weight": 100,
                    "orderNumber": "23"
                }
            ],
            "references": {
                "reference1": "#43 | FD000689 | 41798000200000",
                "reference2": "ref2-2",
                "reference3": "ref3-3",
                "reference4": "ref4-4"
            }
        }
    ],
    "customs": {
        "customsInfo": {
            "reasonForExport": "DOCUMENTS",
            "comments": "Test comment",
            "invoiceNumber": "001189223",
            "importerCustomsReference": "987654",
            "sdrValue": 23.32,
            "EELPFC": "NOEEI 30.2D2",
            "currencyCode": "USD",
            "fromCustomsReference": "EFEFE4554545",
            "licenseNumber": "456ABC123",
            "certificateNumber": "987",
            "customsDeclaredValue": 6000,
            "termsOfSale": "DDP"
        }
    },
    "parcelType": "PKG",
    "rateShopBy": "carrier",
    "byCarrier": {
        "carrierAccountId": "{{ups_carrier_id}}",
        "carrier": "UPS",
        "service": "NDA"
    },
    "shipmentOptions": {
        "addToManifest": true,
        "bypassAddressValidation": "toAddress"
    },
    "references": {
        "reference1": "root-ref1",
        "reference2": "root-ref2",
        "reference3": "root-ref3",
        "reference4": "root-ref4"
    },
    "metadata": [
        {
            "name": "costAccountName",
            "value": "cost account 123"
        }
    ],
    "labelSize": "DOC_4X6",
    "labelType": "SHIPPING_LABEL",
    "labelFormat": "PDF",
    "dateOfShipment": "2026-04-29",
    "deliveryOption": {
        "deliverBy": "2026-05-28",
        "useBestNextDate": false
    }
}
Copy
Copied
{
    "fromAddress": {
        "addressLine1": "27 Waterview Dr",
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484-4301",
        "countryCode": "US",
        "company": "ABC Company",
        "name": "Sasha Sekrotov",
        "phone": "323 555-1212",
        "email": "rs.canid@gmail.com",
        "residential": true
    },
    "toAddress": {
        "company": "Pitney Bowes Inc.",
        "name": "sender_fname",
        "phone": "2032032033",
        "email": "sender@email.com",
        "residential": true,
        "addressLine1": "27 Waterview Drive",
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484-4301",
        "countryCode": "US"
    },
    "parcels": [
        {
            "parcel": {
                "length": 10,
                "width": 10,
                "height": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 2000
            },
            "parcelType": "PKG",
            "specialServices": [
                {
                    "specialServiceId": "ADD_HDL"
                }
            ],
            "items": [
                {
                    "itemId": "sku1",
                    "description": "Book",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "TX",
                    "quantity": 2,
                    "unitPrice": 10,
                    "weightUnit": "GM",
                    "weight": 80,
                    "orderNumber": "22"
                },
                {
                    "itemId": "sku2",
                    "description": "Geometry",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "MB",
                    "quantity": 1,
                    "unitPrice": 101,
                    "weightUnit": "GM",
                    "weight": 432,
                    "orderNumber": "23"
                }
            ],
            "references": {
                "reference1": "#43 | FD000689 | 41798000200000",
                "reference2": "ref2",
                "reference3": "ref3",
                "reference4": "ref4"
            }
        },
        {
            "parcel": {
                "length": 10,
                "width": 10,
                "height": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 1500
            },
            "parcelType": "PKG",
            "items": [
                {
                    "itemId": "sku3",
                    "description": "Jeans",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "NY",
                    "quantity": 2,
                    "unitPrice": 40,
                    "weightUnit": "GM",
                    "weight": 150,
                    "orderNumber": "22"
                },
                {
                    "itemId": "sku4",
                    "description": "Shoes",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "ON",
                    "quantity": 2,
                    "unitPrice": 50,
                    "weightUnit": "GM",
                    "weight": 100,
                    "orderNumber": "23"
                }
            ],
            "references": {
                "reference1": "#43 | FD000689 | 41798000200000",
                "reference2": "ref2-2",
                "reference3": "ref3-3",
                "reference4": "ref4-4"
            }
        }
    ],
    "specialServices": [
        {
            "specialserviceId": "INS",
            "inputParameters": [
                {
                    "name": "INPUT_VALUE",
                    "value": "5000"
                }
            ]
        }
    ],
    "parcelType": "PKG",
    "rateShopBy": "carrier",
    "byCarrier": {
        "carrierAccountId": "{{ups_carrier_id}}",
        "carrier": "UPS",
        "service": "NDA"
    },
    "shipmentOptions": {
        "addToManifest": true,
        "bypassAddressValidation": "toAddress"
    },
    "references": {
        "reference1": "ref1",
        "reference2": "ref2",
        "reference3": "ref3",
        "reference4": "ref4"
    },
    "metadata": [
        {
            "name": "costAccountName",
            "value": "testaccount1727765518"
        }
    ],
    "labelSize": "DOC_4X6",
    "labelType": "SHIPPING_LABEL",
    "labelFormat": "PDF"
}

Create Shipment (By Carrier) sample Response Payloads

Single ParcelSingle Parcel using ParcelsMulti ParcelMulti Parcel (split labels)
Copy
Copied
{
    "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"
    },
    "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"
        }
    ]
}
Copy
Copied
{
    "correlationId": "418b261f7c344fc8b0a5e14074dcf94a",
    "shipmentId": "UPS2202642019792180",
    "carrierAccountId": "ZPeWkjzLXLz3AY8",
    "parcelTrackingNumber": "UPS2202642019792180",
    "labelLayout": [
        {
            "contentType": "URL",
            "contents": "https://prv-labels.gcs.pitneycloud.com/418b261f7c344fc8b0a5e14074dcf94a.pdf",
            "fileFormat": "PDF",
            "size": "DOC_4X6",
            "type": "SHIPPING_LABEL"
        }
    ],
    "rate": {
        "baseCharge": 96.35,
        "baseChargeTaxes": [
            {
                "displayName": "GST",
                "name": "GST",
                "taxAmount": 8.39
            }
        ],
        "carrier": "UPS",
        "currencyCode": "CAD",
        "deliveryCommitment": {
            "estimatedDeliveryDateTime": "2026-05-01 10:30:00",
            "guarantee": "FULL",
            "maxEstimatedNumberOfDays": "1",
            "minEstimatedNumberOfDays": "1"
        },
        "parcelType": "PKG",
        "rateTypeId": "COMMERCIAL",
        "serviceId": "NDA",
        "specialServices": [
            {
                "specialServiceId": "ADD_HDL",
                "fee": 30.05
            }
        ],
        "surcharges": [
            {
                "fee": 42.98,
                "name": "FUEL"
            }
        ],
        "totalCarrierCharge": 176.07,
        "totalTaxAmount": 8.39,
        "isHazmat": false
    },
    "references": {
        "reference1": "root-ref1",
        "reference2": "root-ref2",
        "reference3": "root-ref3",
        "reference4": "root-ref4"
    },
    "parcels": [
        {
            "parcel": {
                "length": 10,
                "height": 10,
                "width": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 2000
            },
            "items": [
                {
                    "itemId": "sku1",
                    "description": "Book",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "TX",
                    "quantity": 2,
                    "unitPrice": 10,
                    "orderNumber": "22",
                    "weightUnit": "GM",
                    "weight": 80
                },
                {
                    "itemId": "sku2",
                    "description": "Geometry",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "MB",
                    "quantity": 1,
                    "unitPrice": 101,
                    "orderNumber": "23",
                    "weightUnit": "GM",
                    "weight": 432
                }
            ]
        }
    ],
    "fromAddress": {
        "addressLine1": "638 Manitoba Ave1",
        "addressLine2": "638 Manitoba Ave2",
        "addressLine3": "638 Manitoba Ave3",
        "cityTown": "Winnipeg",
        "company": "PB & Company",
        "countryCode": "CA",
        "name": "Paul Wright",
        "phone": "203-555-1213",
        "postalCode": "R2W2H2",
        "residential": false,
        "stateProvince": "MB"
    },
    "toAddress": {
        "addressLine1": "947 Hammarskjold Dr1",
        "addressLine2": "947 Hammarskjold Dr2",
        "addressLine3": "947 Hammarskjold Dr3",
        "cityTown": "Burnaby",
        "company": "QA & Company",
        "countryCode": "CA",
        "name": "Paul Wright",
        "phone": "604-320-7572",
        "postalCode": "V5B3C9",
        "residential": false,
        "stateProvince": "BC"
    },
    "altReturnAddress": {
        "addressLine1": "2976 Sherbrooke Ouest1",
        "addressLine2": "2976 Sherbrooke Ouest2",
        "addressLine3": "2976 Sherbrooke Ouest3",
        "cityTown": "Montreal",
        "company": "ABC Company",
        "countryCode": "CA",
        "email": "rs.canid@gmail.com",
        "name": "Rufous Sirius Canid",
        "phone": "323 555-1212",
        "postalCode": "H4A1H3",
        "residential": false,
        "stateProvince": "QC"
    },
    "shipmentOptions": {
        "billingWeight": "2200.0"
    },
    "customs": {
        "customsInfo": {
            "EELPFC": "NOEEI 30.2D2",
            "certificateNumber": "987",
            "comments": "Test comment",
            "currencyCode": "USD",
            "customsDeclaredValue": 0,
            "fromCustomsReference": "EFEFE4554545",
            "importerCustomsReference": "987654",
            "insuredAmount": 0,
            "invoiceNumber": "001189223",
            "licenseNumber": "456ABC123",
            "reasonForExport": "DOCUMENTS",
            "sdrValue": 23.32,
            "termsOfSale": "DDP"
        }
    },
    "soldToAddress": {
        "addressLine1": "47 W 13th St",
        "cityTown": "New York",
        "company": "ABC Company",
        "countryCode": "US",
        "email": "soldTo@email.com",
        "name": "soldToAddress Name",
        "phone": "323 555-1212",
        "postalCode": "10011",
        "residential": false,
        "stateProvince": "NY"
    },
    "carrierPayments": [
        {
            "accountNumber": "4YE336",
            "countryCode": "CA",
            "party": "BILL_SENDER",
            "postalCode": "R2W2H2",
            "typeOfCharge": "TRANSPORTATION_CHARGES"
        },
        {
            "accountNumber": "4YE336",
            "countryCode": "CA",
            "party": "BILL_SENDER",
            "postalCode": "R2W2H2",
            "typeOfCharge": "DUTIES_AND_TAXES"
        }
    ],
    "additionalAddresses": [
        {
            "address": {
                "addressLine1": "2270 US HIGHWAY 130",
                "cityTown": "DAYTON",
                "company": "PB&Cmpany/Co.",
                "countryCode": "US",
                "name": "Warehouse Manager",
                "phone": "732-443-1007",
                "postalCode": "08810-1411",
                "residential": false,
                "stateProvince": "NJ"
            },
            "addressType": "THIRD_PARTY"
        }
    ]
}
Copy
Copied
{
    "correlationId": "5f38f427c35e4f1783e32e3f67be7a76",
    "shipmentId": "UPS2202641925153954",
    "carrierAccountId": "ZPeWkjzLXLz3AY8",
    "parcelTrackingNumber": "UPS2202641925153954P0",
    "labelLayout": [
        {
            "contentType": "URL",
            "contents": "https://225934331380-sending-service-dev.s3.us-east-1.amazonaws.com/temp-labels/UPS2202641925153954P0.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Checksum-Mode=ENABLED&X-Amz-Credential=ASIATJGV4JX2MFQ5KGYP%........................70c1747a034e5c1f5b5bb6a6",
            "fileFormat": "PDF",
            "size": "DOC_4X6",
            "type": "SHIPPING_LABEL"
        }
    ],
    "rate": {
        "baseCharge": 116.1,
        "baseChargeTaxes": [
            {
                "displayName": "GST",
                "name": "GST",
                "taxAmount": 11
            }
        ],
        "carrier": "UPS",
        "currencyCode": "CAD",
        "deliveryCommitment": {
            "estimatedDeliveryDateTime": "2026-05-01 10:30:00",
            "guarantee": "FULL",
            "maxEstimatedNumberOfDays": "1",
            "minEstimatedNumberOfDays": "1"
        },
        "rateTypeId": "commercial",
        "serviceId": "NDA",
        "surcharges": [
            {
                "fee": 73.9,
                "name": "FUEL"
            }
        ],
        "totalCarrierCharge": 228.74,
        "totalTaxAmount": 11,
        "isHazmat": false
    },
    "references": {
        "reference1": "root-ref1",
        "reference2": "root-ref2",
        "reference3": "root-ref3",
        "reference4": "root-ref4"
    },
    "parcels": [
        {
            "parcelType": "PKG",
            "parcel": {
                "length": 10,
                "height": 10,
                "width": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 2000
            },
            "parcelTrackingNumber": "UPS2202641925153954P0",
            "parcelRate": {
                "deliveryCommitment": {
                    "estimatedDeliveryDateTime": "2026-05-01 10:30:00",
                    "guarantee": "FULL",
                    "maxEstimatedNumberOfDays": "1",
                    "minEstimatedNumberOfDays": "1"
                },
                "isHazmat": false
            },
            "specialServices": [
                {
                    "specialServiceId": "ADD_HDL",
                    "fee": 30.05,
                    "brandedName": "Additional Handling"
                }
            ],
            "references": {
                "reference1": "#43 | FD000689 | 41798000200000"
            },
            "items": [
                {
                    "itemId": "sku1",
                    "description": "Book",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "TX",
                    "quantity": 2,
                    "unitPrice": 10,
                    "orderNumber": "22",
                    "weightUnit": "GM",
                    "weight": 80
                },
                {
                    "itemId": "sku2",
                    "description": "Geometry",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "MB",
                    "quantity": 1,
                    "unitPrice": 101,
                    "orderNumber": "23",
                    "weightUnit": "GM",
                    "weight": 432
                }
            ]
        },
        {
            "parcelType": "PKG",
            "parcel": {
                "length": 10,
                "height": 10,
                "width": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 1500
            },
            "parcelTrackingNumber": "UPS2202641925153954P1",
            "parcelRate": {
                "deliveryCommitment": {
                    "estimatedDeliveryDateTime": "2026-05-01 10:30:00",
                    "guarantee": "FULL",
                    "maxEstimatedNumberOfDays": "1",
                    "minEstimatedNumberOfDays": "1"
                },
                "isHazmat": false
            },
            "references": {
                "reference1": "#43 | FD000689 | 41798000200000"
            },
            "items": [
                {
                    "itemId": "sku3",
                    "description": "Jeans",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "NY",
                    "quantity": 2,
                    "unitPrice": 40,
                    "orderNumber": "22",
                    "weightUnit": "GM",
                    "weight": 150
                },
                {
                    "itemId": "sku4",
                    "description": "Shoes",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "ON",
                    "quantity": 2,
                    "unitPrice": 50,
                    "orderNumber": "23",
                    "weightUnit": "GM",
                    "weight": 100
                }
            ]
        }
    ],
    "fromAddress": {
        "addressLine1": "638 Manitoba Ave1",
        "addressLine2": "638 Manitoba Ave2",
        "addressLine3": "638 Manitoba Ave3",
        "cityTown": "Winnipeg",
        "company": "PB & Company",
        "countryCode": "CA",
        "name": "Paul Wright",
        "phone": "203-555-1213",
        "postalCode": "R2W2H2",
        "residential": false,
        "stateProvince": "MB"
    },
    "toAddress": {
        "addressLine1": "947 Hammarskjold Dr1",
        "addressLine2": "947 Hammarskjold Dr2",
        "addressLine3": "947 Hammarskjold Dr3",
        "cityTown": "Burnaby",
        "company": "QA & Company",
        "countryCode": "CA",
        "name": "Paul Wright",
        "phone": "604-320-7572",
        "postalCode": "V5B3C9",
        "residential": false,
        "stateProvince": "BC"
    },
    "altReturnAddress": {
        "addressLine1": "2976 Sherbrooke Ouest1",
        "addressLine2": "2976 Sherbrooke Ouest2",
        "addressLine3": "2976 Sherbrooke Ouest3",
        "cityTown": "Montreal",
        "company": "ABC Company",
        "countryCode": "CA",
        "email": "rs.canid@gmail.com",
        "name": "Rufous Sirius Canid",
        "phone": "323 555-1212",
        "postalCode": "H4A1H3",
        "residential": false,
        "stateProvince": "QC"
    },
    "shipmentOptions": {
        "bypassAddressValidation": "toAddress",
        "billingWeight": "144.0"
    },
    "customs": {
        "customsInfo": {
            "EELPFC": "NOEEI 30.2D2",
            "certificateNumber": "987",
            "comments": "Test comment",
            "currencyCode": "USD",
            "customsDeclaredValue": 0,
            "fromCustomsReference": "EFEFE4554545",
            "importerCustomsReference": "987654",
            "insuredAmount": 0,
            "invoiceNumber": "001189223",
            "licenseNumber": "456ABC123",
            "reasonForExport": "DOCUMENTS",
            "sdrValue": 23.32,
            "termsOfSale": "DDP"
        }
    },
    "soldToAddress": {
        "addressLine1": "47 W 13th St",
        "cityTown": "New York",
        "company": "ABC Company",
        "countryCode": "US",
        "email": "soldTo@email.com",
        "name": "soldToAddress Name",
        "phone": "323 555-1212",
        "postalCode": "10011",
        "residential": false,
        "stateProvince": "NY"
    },
    "carrierPayments": [
        {
            "accountNumber": "4YE336",
            "countryCode": "CA",
            "party": "BILL_SENDER",
            "postalCode": "R2W2H2",
            "typeOfCharge": "TRANSPORTATION_CHARGES"
        },
        {
            "accountNumber": "4YE336",
            "countryCode": "CA",
            "party": "BILL_SENDER",
            "postalCode": "R2W2H2",
            "typeOfCharge": "DUTIES_AND_TAXES"
        }
    ],
    "additionalAddresses": [
        {
            "address": {
                "addressLine1": "2270 US HIGHWAY 130",
                "cityTown": "DAYTON",
                "company": "PB&Cmpany/Co.",
                "countryCode": "US",
                "name": "Warehouse Manager",
                "phone": "732-443-1007",
                "postalCode": "08810-1411",
                "residential": false,
                "stateProvince": "NJ"
            },
            "addressType": "THIRD_PARTY"
        }
    ]
}
Copy
Copied
{
    "correlationId": "2e44c3496d784501bd23a82bc35f2350",
    "shipmentId": "UPS2202642019578998",
    "carrierAccountId": "ZPeWkjzLXLz3AY8",
    "parcelTrackingNumber": "UPS2202642019578998P0",
    "rate": {
        "baseCharge": 116.1,
        "baseChargeTaxes": [
            {
                "displayName": "GST",
                "name": "GST",
                "taxAmount": 11
            }
        ],
        "carrier": "UPS",
        "currencyCode": "CAD",
        "deliveryCommitment": {
            "estimatedDeliveryDateTime": "2026-05-01 10:30:00",
            "guarantee": "FULL",
            "maxEstimatedNumberOfDays": "1",
            "minEstimatedNumberOfDays": "1"
        },
        "rateTypeId": "commercial",
        "serviceId": "NDA",
        "surcharges": [
            {
                "fee": 73.9,
                "name": "FUEL"
            }
        ],
        "totalCarrierCharge": 228.74,
        "totalTaxAmount": 11,
        "isHazmat": false
    },
    "references": {
        "reference1": "root-ref1",
        "reference2": "root-ref2",
        "reference3": "root-ref3",
        "reference4": "root-ref4"
    },
    "parcels": [
        {
            "parcelType": "PKG",
            "parcel": {
                "length": 10,
                "height": 10,
                "width": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 2000
            },
            "parcelTrackingNumber": "UPS2202642019578998P0",
            "parcelRate": {
                "deliveryCommitment": {
                    "estimatedDeliveryDateTime": "2026-05-01 10:30:00",
                    "guarantee": "FULL",
                    "maxEstimatedNumberOfDays": "1",
                    "minEstimatedNumberOfDays": "1"
                },
                "isHazmat": false
            },
            "specialServices": [
                {
                    "specialServiceId": "ADD_HDL",
                    "fee": 30.05,
                    "brandedName": "Additional Handling"
                }
            ],
            "document": {
                "contentType": "URL",
                "contents": "https://prv-labels.gcs.pitneycloud.com/2e44c3496d784501bd23a82bc35f2350-0-0.pdf",
                "fileFormat": "PDF",
                "size": "DOC_4X6",
                "type": "SHIPPING_LABEL"
            },
            "references": {
                "reference1": "#43 | FD000689 | 41798000200000"
            },
            "items": [
                {
                    "itemId": "sku1",
                    "description": "Book",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "TX",
                    "quantity": 2,
                    "unitPrice": 10,
                    "orderNumber": "22",
                    "weightUnit": "GM",
                    "weight": 80
                },
                {
                    "itemId": "sku2",
                    "description": "Geometry",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "MB",
                    "quantity": 1,
                    "unitPrice": 101,
                    "orderNumber": "23",
                    "weightUnit": "GM",
                    "weight": 432
                }
            ]
        },
        {
            "parcelType": "PKG",
            "parcel": {
                "length": 10,
                "height": 10,
                "width": 10,
                "dimUnit": "CM",
                "weightUnit": "GM",
                "weight": 1500
            },
            "parcelTrackingNumber": "UPS2202642019578998P1",
            "parcelRate": {
                "deliveryCommitment": {
                    "estimatedDeliveryDateTime": "2026-05-01 10:30:00",
                    "guarantee": "FULL",
                    "maxEstimatedNumberOfDays": "1",
                    "minEstimatedNumberOfDays": "1"
                },
                "isHazmat": false
            },
            "document": {
                "contentType": "URL",
                "contents": "https://prv-labels.gcs.pitneycloud.com/2e44c3496d784501bd23a82bc35f2350-1-0.pdf",
                "fileFormat": "PDF",
                "size": "DOC_4X6",
                "type": "SHIPPING_LABEL"
            },
            "references": {
                "reference1": "#43 | FD000689 | 41798000200000"
            },
            "items": [
                {
                    "itemId": "sku3",
                    "description": "Jeans",
                    "hSTariffCode": "490191",
                    "originCountryCode": "US",
                    "originStateProvince": "NY",
                    "quantity": 2,
                    "unitPrice": 40,
                    "orderNumber": "22",
                    "weightUnit": "GM",
                    "weight": 150
                },
                {
                    "itemId": "sku4",
                    "description": "Shoes",
                    "hSTariffCode": "490191",
                    "originCountryCode": "CA",
                    "originStateProvince": "ON",
                    "quantity": 2,
                    "unitPrice": 50,
                    "orderNumber": "23",
                    "weightUnit": "GM",
                    "weight": 100
                }
            ]
        }
    ],
    "fromAddress": {
        "addressLine1": "638 Manitoba Ave1",
        "addressLine2": "638 Manitoba Ave2",
        "addressLine3": "638 Manitoba Ave3",
        "cityTown": "Winnipeg",
        "company": "PB & Company",
        "countryCode": "CA",
        "name": "Paul Wright",
        "phone": "203-555-1213",
        "postalCode": "R2W2H2",
        "residential": false,
        "stateProvince": "MB"
    },
    "toAddress": {
        "addressLine1": "947 Hammarskjold Dr1",
        "addressLine2": "947 Hammarskjold Dr2",
        "addressLine3": "947 Hammarskjold Dr3",
        "cityTown": "Burnaby",
        "company": "QA & Company",
        "countryCode": "CA",
        "name": "Paul Wright",
        "phone": "604-320-7572",
        "postalCode": "V5B3C9",
        "residential": false,
        "stateProvince": "BC"
    },
    "altReturnAddress": {
        "addressLine1": "2976 Sherbrooke Ouest1",
        "addressLine2": "2976 Sherbrooke Ouest2",
        "addressLine3": "2976 Sherbrooke Ouest3",
        "cityTown": "Montreal",
        "company": "ABC Company",
        "countryCode": "CA",
        "email": "rs.canid@gmail.com",
        "name": "Rufous Sirius Canid",
        "phone": "323 555-1212",
        "postalCode": "H4A1H3",
        "residential": false,
        "stateProvince": "QC"
    },
    "shipmentOptions": {
        "bypassAddressValidation": "toAddress",
        "billingWeight": "144.0"
    },
    "customs": {
        "customsInfo": {
            "EELPFC": "NOEEI 30.2D2",
            "certificateNumber": "987",
            "comments": "Test comment",
            "currencyCode": "USD",
            "customsDeclaredValue": 0,
            "fromCustomsReference": "EFEFE4554545",
            "importerCustomsReference": "987654",
            "insuredAmount": 0,
            "invoiceNumber": "001189223",
            "licenseNumber": "456ABC123",
            "reasonForExport": "DOCUMENTS",
            "sdrValue": 23.32,
            "termsOfSale": "DDP"
        }
    },
    "soldToAddress": {
        "addressLine1": "47 W 13th St",
        "cityTown": "New York",
        "company": "ABC Company",
        "countryCode": "US",
        "email": "soldTo@email.com",
        "name": "soldToAddress Name",
        "phone": "323 555-1212",
        "postalCode": "10011",
        "residential": false,
        "stateProvince": "NY"
    },
    "carrierPayments": [
        {
            "accountNumber": "4YE336",
            "countryCode": "CA",
            "party": "BILL_SENDER",
            "postalCode": "R2W2H2",
            "typeOfCharge": "TRANSPORTATION_CHARGES"
        },
        {
            "accountNumber": "4YE336",
            "countryCode": "CA",
            "party": "BILL_SENDER",
            "postalCode": "R2W2H2",
            "typeOfCharge": "DUTIES_AND_TAXES"
        }
    ],
    "additionalAddresses": [
        {
            "address": {
                "addressLine1": "2270 US HIGHWAY 130",
                "cityTown": "DAYTON",
                "company": "PB&Cmpany/Co.",
                "countryCode": "US",
                "name": "Warehouse Manager",
                "phone": "732-443-1007",
                "postalCode": "08810-1411",
                "residential": false,
                "stateProvince": "NJ"
            },
            "addressType": "THIRD_PARTY"
        }
    ]
}

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.