Create a CBDS International Outbound Shipment

HTTP Request

POST /v1/shipments?carrier=PBI&includeDeliveryCommitment=true

Summary

This operation creates a CBDS shipment from an origin address in the U.S., UK, or Canada to an international destination. The operation returns an end-to-end tracking number from the origin address to the international destination. The shipment is a post-paid shipment.

Prerequisite

To ship with International Outbound, a merchant must be enabled. To request enablement, merchants must contact their Pitney Bowes implementation managers or email either GEC-TechSupport@pb.com or ShippingAPIBusinessDevelopment@pb.com. During enablement, a merchant sets up one or more delivery solutions.

Delivery Solutions for International Outbound

The delivery solution determines how the parcel arrives at the CBDS Hub before international shipment and determines whether the API prints a shipping label. The following table provides brief descriptions of the solutions. For detailed descriptions, see International Outbound Solutions on the CBDS Delivery Solutions page.

Merchants can have multiple delivery solutions and can add delivery solutions by contacting their PB implementation managers. When issuing this API request, the merchant chooses the solution to use by passing a value through the DELIVERY_SOLUTION option in the shipmentOptions array. The table shows the value to pass. The delivery solutions available depend on the origin country, as specified in the table.

Solution

Origin Country

Description


DELIVERY_SOLUTION takes this value:

Piece-Level Shipment

U.S.

The API prints a USPS label for delivery to a CBDS Hub.

FIRSTMILE

Bulk Pickup

U.S.

Available for merchants who ship more than 200 parcels a day. The API prints a PB Delivery label.

PICKUP_STANDARDLABEL

Drop-Off / Pickup to PB Delivery

U.S.

The API prints a PB Delivery label for delivery from a PB Delivery facility to a CBDS Hub or Pitney Bowes picks up the PB Delivery parcels and brings to the CBDS Hub. The label must include “Attn: PB Cross-Border” on Address Line 1. Note The merchant delivers or picks up the parcel at the PB Delivery facility.

-PICKUP_STANDARDLABEL -DROPOFF_STANDARDLABEL

Drop-Off / Pickup to CBDS

U.S., UK

The API does not print a label. The merchant prints the first-mile label prior to calling the API.

  • Provide the first-mile label’s tracking number when invoking the API or the parcel will be unrecognized at the hub.

  • Do not enter a Client ID when invoking the API. Doing so throws an error.

  • DROPOFF_CLIENTLABEL: Merchant delivers parcel to hub

  • PICKUP_CLIENTLABEL: Pitney Bowes picks up parcel

Drop-Off / Pickup to CBDS with Generic Label

U.S., UK

The API prints a generic label the merchant uses to deliver the parcels to the CBDS Hub or Pitney Bowes picks up the parcels and brings to the CBDS.

  • DROPOFF_GENERICLABEL: Merchant delivers parcel to hub

  • PICKUP_GENERICLABEL: Pitney Bowes picks up parcel

Drop-Off / Pickup to CBDS with Final-Mile Label

Canada

The API prints the final-mile label for delivery from a CBDS Hub to the final destination. The merchant delivers or picks up the parcel at the hub. The merchant attaches the final-mile label prior to delivery.

  • DROPOFF_FINALMILELABEL: Merchant delivers parcel to hub

  • PICKUP_FINALMILELABEL: Domestic carrier picks up parcel

Considerations

  1. If the API returns a label, the label must be used within 14 days.

  2. Do not pass the specialServices array in the request. If you do, the API will ignore the array. Note, however, that the response might return the array with the DelCon special service, which is a no-charge service.

  3. The EU requires shippers include a VAT or IOSS number. This number is associated with the merchant’s Shipper ID. By entering the Shipper ID (which you do in shipmentOptions), CBDS handles everything else to meet the EU requirement. For CBDS the VAT or IOSS it is only required for PB Delivery DDP.

  4. Fuel surcharges are available as a downloadable spreadsheet.

    Download the Fuel Surcharge spreadsheet

  5. The API response returns:

    • The estimated charges, which include the Transportation cost and, if applicable, the Importation costs.

    • The tracking number for the parcel’s full journey, from the origin address to the international destination.

    • If applicable, the label for delivery to the CBDS Hub.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/shipments?carrier=PBI&includeDeliveryCommitment=true
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/shipments?carrier=PBI&includeDeliveryCommitment=true

Query Parameter

Name

Description

carrier

Required. Set this to PBI.

includeDeliveryCommitment

Required. If set to true, returns estimated transit time. Transit time is returned as number of days.

Valid values:

  • true

  • false

Request Headers

Name


Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

Content-Type

Required. The media type of the request entity. Set this to application/json.

X-PB-TransactionId

Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Important: Ensure this is unique.

X-PB-UnifiedErrorStructure

Recommended. Set this to true to use the standard error object if an error occurs.

Request / Response Elements

Required fields are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

Name


Data TypeF

Description

fromAddress

Address Object

Required. The shipment’s origin address. For CBDS Outbound the origin will be the shipper’s facility, and the destination will be the ultimate consignee address in the foreign country. If the shipper is a marketplace shipper, see additionalAddresses below.

The fromAddress object requires the following fields:

  • name: Enter both the first and last name. If the correct name is not entered the parcel might be delayed at customs or returned.

  • phone: Enter the correct phone number to avoid delays or returns.

  • addressLines

  • cityTown

  • stateProvince: Required for Canadian addresses.

  • postalCode: Required for all call/service types.

  • countryCode

toAddress

Address Object

Required. The shipment’s destination address. The following fields are required:

  • name: Enter both the first and last name. If the correct name is not entered the parcel might be delayed at customs or returned.

  • phone: Enter the correct phone number to avoid delays or returns.

  • addressLines

  • cityTown

  • stateProvince: Required for Canadian addresses.

  • postalCode: Required for all call/service types. See also: Rules for Destination Postal Codes

  • countryCode

altReturnAddress

Address Object

By default, parcel returns are sent from the CBDS Hub to the shipment’s fromAddress. If the address entered in fromAddress is not the address for the merchant’s returns, use this object to enter the correct returns address. Failure to do so will result in returns going to the wrong address. The altReturnAddress object requires the following fields:

  • name: Enter both the first and last name. If the correct name is not entered the parcel might be delayed at customs or returned.

  • addressLines

  • cityTown

  • stateProvince: Required for Canadian addresses.

  • postalCode: Required for all call/service types.

  • countryCode

additionalAddresses

Array[Object]

Marketplace Shippers Only. The seller’s address. This array applies to marketplace shippers, which are shippers who use the same SHIPPER_ID for all sellers and who then give each seller a unique seller ID. Enter the marketplace shipper’s address in the fromAddress field and enter the seller’s address here. When you use this field, you must also include the SELLER_ID option in the shipmentOptions array. See the sample request below.

additionalAddresses.addressType

String

Set this to the following: SELLER

additionalAddresses.address

Address Object

The seller’s address.

parcel

Parcel Object

Required. The parcel’s weight and dimensions.

Important

Enter the correct weight, or the package will be rejected.

rates

Array[Rates Object]

Required. Specifies the carrier, service, and parcel type. The response specifies the service charges. The array takes one rates object. The object requires the following fields and values:

Field:

Value:

carrier

PBI

parcelType

PKG

serviceId

Set to one of the following service classes, depending on the country of origin. The available classes also depend on the merchant’s delivery agreement and the shipping lane:

U.S. Outbound:

  • PBXPE: Expedited DDP

  • PBXPS: PB Delivery DDP

  • PBXUS: PB Delivery DDU

UK Outbound:

  • PBXPS: PB Delivery DDP

Canada Outbound:

  • PBXPS: PB Delivery DDP

documents

Array[Documents Object]

Required for delivery solutions that print the first-mile label. Defines the label’s size, file format, and content type. In the response, the array returns the label as a URL or Base64 string. Do not use this field if the merchant prints the first-mile label prior to invoking this API. This object requires the following fields:

Field:

Value:

type

SHIPPING_LABEL

printDialogOption

Set as described here

size,
fileFormat,
contentType

For valid combinations of values, see Labels on the CBDS page.

shipmentOptions

Array[Object]

Required. Each object in this array defines a shipment option. Each object takes the following two fields, which take string values:

The following options are required or conditional:

  • SHIPPER_ID: Required. Enter the merchant’s Shipper ID, which is found in the postalReportingNumber field returned by the Merchants API.

  • DELIVERY_SOLUTION: Required. Enter the value for the shipment’s delivery solution as specified in the Delivery Solutions table above. NOTE: This option is not required for accounts created prior to April 2023 that use only one solution.

  • CLIENT_ID: Conditional. Required for delivery solutions that print a PB Delivery label. Enter the merchant’s ID for access to CBDS.

  • CLIENT_FACILITY_ID: Conditional. Required for delivery solutions that print a PB Delivery label. Enter the ID for the merchant’s facility.

  • CARRIER_FACILITY_ID: Conditional. Required for all Drop-Off solutions and for the Bulk Pickup solution. Enter the ID of the CBDS Hub that will receive the parcel.

  • SELLER_ID: Conditional. Required if the additionalAddresses array is used. Set this to the seller ID that the marketplace shipper has shared with Pitney Bowes in advance. A marketplace shipper is a shipper who uses the same SHIPPER_ID for all sellers and specifies the individual seller through this SELLER_ID option. If you use this option, you must also specify the seller’s address in the additionalAddresses array.

customs

Object

Required. Currency and commodity information.

customs.customsInfo

Object

Required. Sets the currency code.

customs.customsInfo.currencyCode

String

Required. Sets the currency code. Set to one of the following, depending on the origin country:

  • U.S.: USD

  • UK: GBP

  • Canada: CAD

customs.customsItems

Array[Customs Items Object]

Required. Commodity information for customs clearance. The array takes a maximum of 30 objects.

domesticShipmentDetails

Object

Required for Drop-Off to CBDS. Response Only for all other solutions. For Drop-Off to CBDS, enter the first-mile label’s tracking number and details.

Important

Failure to provide the tracking number for drop-off to CBDS will result in the parcel being unrecognized at the CBDS Hub.

references

Array[Object]

Required for Bulk Pickup. Optional for all other solutions. Enter merchant-generated reference fields. Pitney Bowes includes the reference fields in tracking files and invoices. Each object in the array takes the following two elements:

  • name: The type of reference field. The name element takes one of the following String values:

    • ORDER_NUMBER: Indicates the reference field is a merchant-generated order ID. The order ID cannot have spaces when entered in the value element. ORDER_NUMBER max is 50.

    • ReferenceNumber: Indicates the reference field is a merchant-generated reference number. ReferenceNumber max is 100. NOTE: Reference Number is not applicable for Intra Canada.

  • value: The value of the reference field, entered as a String.

shipmentId

String

RESPONSE ONLY. The unique identifier for the shipment generated by the system.

parcelTrackingNumber

String

RESPONSE ONLY. The tracking number assigned to the shipment.

Customs Items Object for CBDS International Outbound

Name


Data Type


Description


description

String

Required. Provide a highly detailed description of the commodity to facilitate assignment of the correct HS code. See the following examples:

"description": "Acme AC8431 Rechargeable Hand Blender with Electric Attachments"

"description": "Antique Vintage Victorian Edwardian Walnut Writing Stationery Box"

"description": "Pitney Bowes 793-5 Fluorescent Red Ink Cartridge DM100 DM200"

Maximum length: 255 characters

hazmat

Array[String]

For a HAZMAT-flagged item, enter one or more of the HAZMAT classifications listed here.

hSTariffCode

String

The destination country’s tariff-classification number for the commodity. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and add additional digits for more detail.

Maximum length: 14 characters

hSTariffCodeCountry

String

The two-character ISO Country Code for the country supplying the HS code. This is usually the destination country. This is required if the hSTariffCode field is used.

itemDimension

Dimension Object

The dimensions for a single item.

itemId

String

Required. The merchant’s unique identifier for the commodity, such as the SKU or item code. The value might be used to verify the product during customs clearance. To avoid shipment delays, the value should be unique for individual variants of a product.

To avoid problems processing the order data, make sure the value does not include leading or trailing spaces.

Maximum length: 50 characters

manufacturer

String

The manufacturer of the item.

Maximum length: 255 characters

originCountryCode

String

The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.

quantity

Integer

Required. The total number of items of this type of commodity.

unitPrice

BigDecimal

Required. The price of one item of this type of commodity.

unitWeight

Object

The weight and unit of measure of one item of the commodity.

unitWeight.weight

Number

The weight of the item. This field is required by the unitWeight object. Our platform only stores up to 4 decimal places, rounding up. (Example: If passed 0.005591111111111 in the API, 0.0056 is persisted).

unitWeight.unitOfMeasurement

String

The unit of measurement. This field is required by the unitWeight object. This field can take the following values:

  • OZ: Ounces

  • GM: Grams

  • G: Grams

  • LB: Pounds

  • KG: Kilograms

url

String

Required. Enter the commodity’s URL on the merchant site. Ensure the URL works. The URL helps Pitney Bowes assign the correct HS code. If the merchant does not have a URL, you can pass an empty string ("url:"").

Maximum length: 1000 characters

Domestic Shipment Details Object

Name


Data Type

Description

shipperTrackingNumber

String

The tracking number for the domestic leg of the CBDS shipment.

Required if this object is sent in the request.

barCodeLabelNumber

String

The tracking number for the domestic leg of the CBDS shipment. This number also appears in the shipperTrackingNumber field.

carrier

String

The carrier for the domestic leg of the CBDS shipment. Possible values include: USPS, DHL (DHL Express), FedEx, UPS.

dcAddress

Address Object

The origin address for the domestic leg of the CBDS shipment. The parcel is shipped from this address to the CBDS Hub.

Sample Requests

This section provides the following sample requests:

For this solution:


See this example:


Piece-Level Shipment

Sample Request to Return a USPS Label

Bulk Pickup

Sample Request to Return a PB Label

Drop-Off to PB Returns

Sample Request to Return a PB Label

Drop-Off to CBDS (U.S. Outbound)

Sample Request for Drop-Off to CBDS (U.S. Outbound)

Drop-Off / Pickup to CBDS (UK Outbound)

Sample Request for Drop-Off to CBDS (UK Outbound)

Drop-Off / Pickup to CBDS with Generic Label (UK Outbound)

Sample Request for Drop-Off to CBDS with Generic Label (US & UK Outbound)

Drop-Off / Pickup to CBDS (Canada Outbound)

Sample Request for Drop-Off to CBDS (Canada Outbound)

Specify SELLER_ID for a Marketplace Shipper. (This sample is not specific to a solution.)

Sample Request that Specifies a SELLER_ID

Specify SELLER_ID for a Marketplace Shipper. (This sample is not specific to a solution.)

Sample Request that Specifies a SELLER_ID

Hazmat (US Outbound)

Sample Request for CBDS US Outbound Hazmat


Sample Request to Return a USPS Label

The following request uses the Piece-Level Shipment solution and prints a USPS label. A sample label is shown after the example.

Sample Request to Return a USPS Label
curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "dimension": {
            "length": "12",
            "width": "5",
            "height": "10",
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 80,
            "unitOfMeasurement": "OZ"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "resolution": "DPI_203",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "FIRSTMILE"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "description": "vintage floral-print patchwork long-sleeve cotton linen dress with pockets",
            "hSTariffCode": "610442",
            "hSTariffCodeCountry": "US",
            "itemId": "54378DRE",
            "quantity": 2,
            "unitPrice": 100.00,
            "url": "https://www.example.com/shop/women/clothing/dress/54378DRE"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ]
}'
Sample Response that Returns a USPS Label
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 12,
            "height": 10,
            "width": 5,
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 80,
            "unitOfMeasurement": "OZ"
        },
        "valueOfGoods": 200.0
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "DelCon",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "0"
            } ],
            "fee": 0.00
        } ],
        "inductionPostalCode": "36830",
        "dimensionalWeight": {
            "weight": 0.0,
            "unitOfMeasurement": "OZ"
        },
        "baseCharge": 42.22,
        "totalCarrierCharge": 89.87,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "5",
            "maxEstimatedNumberOfDays": "8"
        },
        "currencyCode": "USD",
        "destinationZone": 4,
        "totalDutyAmount": 16.20,
        "totalTaxAmount": 31.45
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "contentType": "URL",
        "contents": "https://.../usps/325584758/outbound/label/9d1da50f82734ab9d4a41d5ffb9a19b.pdf"
        }
    ],
    "shipmentOptions": [ {
        "name": "HIDE_TOTAL_CARRIER_CHARGE",
        "value": "false"
    },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "ADD_TO_MANIFEST",
        "value": "false"
    },{
        "name": "FUTURE_SHIPMENT_DATE",
        "value": "2020-10-06 16:35:26.327"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
    },{
        "name": "SHIPPING_LABEL_RECEIPT",
        "value": "noOptions"
    },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "UPPBX0015B2A0E60EF73"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "FIRSTMILE"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "54378DRE",
            "description": "vintage floral-print patchwork long-sleeve cotton linen dress with pockets",
            "quantity": 2,
            "unitPrice": 100.00,
            "url": "https://www.example.com/shop/women/clothing/dress/54378DRE",
            "hSTariffCode": "610442",
            "hSTariffCodeCountry": "US"
        } ]
    },
    "domesticShipmentDetails": { ... },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ],
    "parcelTrackingNumber": "SBXCZ000000002135402",
    "shipmentId": "SBXCZ000000002135402"
}

Sample Label for Piece-Level Shipment

The following is a sample USPS label returned for the Piece-Level Shipment delivery solution.

Sample Label Returned for Piece-Level Shipment Solution



Sample Request to Return a PB Label

Use the following request for both the Bulk Pickup and Drop-Off to PB Delivery solutions. See the sample label after this example.

Sample Request to Return a PB Label
curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=false" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "dimension": {
            "unitOfMeasurement": "in",
            "length": "2.15",
            "width": "2",
            "height": "3",
            "irregularParcelGirth": "2"
        },
        "weight": {
            "unitOfMeasurement": "Lb",
            "weight": "2"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    },{
        "name": "CLIENT_FACILITY_ID",
        "value": "2067"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "0921"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "PICKUP_STANDARDLABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "description": "Sample Items Acme AC8431 Rechargeable Hand Blender with Electric Attachments",
            "quantity": 1,
            "unitPrice": 164,
            "unitWeight": {
                "weight": 2,
                "unitOfMeasurement": "Lb"
            },
            "hSTariffCode": "0",
            "originCountryCode": "MX",
            "url": "https://example.com/blender",
            "itemId": "85-SKU",
            "hSTariffCodeCountry": "US"
          } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    },{
        "name": "ReferenceNumber",
        "value": "321789"
    } ]
}'
Sample Response that Returns a PB Label
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 2.15,
            "height": 3,
            "width": 2,
            "unitOfMeasurement": "in",
            "irregularParcelGirth": "2"
        },
        "weight": {
            "weight": 2,
            "unitOfMeasurement": "Lb"
        },
        "valueOfGoods": 164.0
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "DelCon",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "0"
            } ]
        } ],
        "baseCharge": 21.14,
         "totalCarrierCharge": 29.34,
         "currencyCode": "USD",
         "totalTaxAmount": 8.20
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "contents": "https://.../4d864381fb1a4c8ba678e2e8d867abcd.pdf"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    },{
        "name": "CLIENT_FACILITY_ID",
        "value": "2067"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "0921"
    },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "UPPBX0016FF5B249E826"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "PICKUP_STANDARDLABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "85-SKU",
            "description": "Sample Items Acme AC8431 Rechargeable Hand Blender with Electric Attachments",
            "quantity": 1,
            "unitPrice": 164.00,
            "url": "https://example.com/blender",
            "unitWeight": {
                "weight": 2,
                "unitOfMeasurement": "Lb"
            },
            "originCountryCode": "MX",
            "hSTariffCode": "0",
            "hSTariffCodeCountry": "US"
        } ]
    },
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "7624003NGST0000000000D",
        "barCodeLabelNumber": "7624003NGST0000000000D"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    },{
        "name": "ReferenceNumber",
        "value": "321789"
    } ],
    "parcelTrackingNumber": "UPPBX0016FF5B249E826",
    "shipmentId": "UPPBX0016FF5B249E826"
}

Sample PB Label

The following is a sample PB label returned by the Bulk Pickup and Drop-Off to PB Delivery solutions.

Sample PB Label



Sample Request for Drop-Off to CBDS (U.S. Outbound)

The following is a sample request for a U.S. Outbound shipment that uses the Drop-Off to CBDS solution. The request does not return a label. Instead, the merchant must print a first-mile label prior to invoking the API. When making the API call, pass the first-mile label’s tracking number through the domesticShipmentDetails object.

The value of the request’s DELIVERY_SOLUTION option depends on whether the merchant delivers the parcel to the hub or Pitney Bowes picks it up. For values, see this table. In this example, the merchant delivers the parcel to the hub.

Sample Request for Drop-Off to CBDS (U.S. Outbound)
curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "dimension": {
            "length": "16",
            "width": "12",
            "height": "2",
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 24,
            "unitOfMeasurement": "OZ"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_CLIENTLABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "description": "clothing men's shirt casual button-down slim fit cotton wrinkle-free single-needle construction",
            "hSTariffCode": "6205200010",
            "hSTariffCodeCountry": "CA",
            "itemId": "43953AE0",
            "quantity": 1,
            "unitPrice": 45.00,
            "url": "https://www.example.com/shop/43953AE0"
        } ]
    },
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "USPS13600000008398",
        "carrier": "USPS"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ]
}'
Sample Response for Drop-Off to CBDS (U.S. Outbound)
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 16,
            "height": 2,
            "width": 12,
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 24,
            "unitOfMeasurement": "OZ"
        },
        "valueOfGoods": 125.00
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "baseCharge": 41.38,
        "totalCarrierCharge": 49.69,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "6",
            "maxEstimatedNumberOfDays": "9"
        },
        "currencyCode": "USD",
        "totalTaxAmount": 8.31
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_CLIENTLABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "43953AE0",
            "description": "clothing men's shirt casual button-down slim fit cotton wrinkle-free single-needle construction",
            "quantity": 1,
            "unitPrice": 45.00,
            "url": "https://www.example.com/shop/43953AE0",
            "hSTariffCode": "6205200010",
            "hSTariffCodeCountry": "CA"
        } ]
    },
    "domesticShipmentDetails": {
        "carrier": "USPS",
        "shipperTrackingNumber": "USPS13600000008398"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ],
    "parcelTrackingNumber": "SBXCZ000000002140172",
    "shipmentId": "SBXCZ000000002140172"
}



Sample Request for Drop-Off to CBDS (UK Outbound)

The following is a sample request for a UK Outbound shipment that uses the Drop-Off to CBDS solution. The request does not return a label. Instead, the merchant must print the first-mile label prior to the API call and pass the label’s tracking number when making the API call.

The value of the request’s DELIVERY_SOLUTION option depends on whether the merchant delivers the parcel to the hub or Pitney Bowes picks it up. For values, see this table. In this example, the merchant delivers the parcel to the hub.

Sample Request for Drop-Off to CBDS UK
curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "dimension": {
            "length": "6",
            "width": "8",
            "height": "9",
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": "0.0"
        },
        "weight": {
            "unitOfMeasurement": "LB",
            "weight": "2"
        },
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "GB_GEODIS_GBA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_CLIENTLABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "GBP"
        },
        "customsItems": [ {
            "itemId": "880682",
            "description": "clothing men's shirt casual button-down slim fit cotton wrinkle-free single-needle construction",
            "quantity": "2",
            "unitPrice": "100.00",
            "url": "https://www.example.com/uk/shop/880682",
            "hSTariffCode": "620120",
            "hSTariffCodeCountry": "US",
            "originCountryCode": "GB"
        } ]
    },
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "4039180763478-245789",
        "carrier": "FEDEX",
        "dcAddress": { ... }
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "MerchantOrder-2583"
    } ]
}'
Sample Response for Drop-Off to CBDS UK
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 6,
            "height": 9,
            "width": 8,
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 2.0,
            "unitOfMeasurement": "LB"
        },
        "valueOfGoods": 200.0
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG"
        "baseCharge": 15.76,
        "totalCarrierCharge": 221.12,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "4",
            "maxEstimatedNumberOfDays": "8"
         },
         "currencyCode": "GBP",
         "totalDutyAmount": 110.88,
         "totalTaxAmount": 94.48
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "GB_GEODIS_GBA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_CLIENTLABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "GBP"
        },
        "customsItems": [ {
            "itemId": "880682",
            "description": "clothing men's shirt casual button-down slim fit cotton wrinkle-free single-needle construction",
            "quantity": "2",
            "unitPrice": "100.00",
            "url": "https://www.example.com/uk/shop/880682",
            "hSTariffCode": "620120",
            "hSTariffCodeCountry": "US",
            "originCountryCode": "GB"
        } ]
    },
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "4039180763478-245789",
        "carrier": "FEDEX",
        "dcAddress": { ... }
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "MerchantOrder-2583"
    } ],
    "parcelTrackingNumber": "PBXAA000000010030065",
    "shipmentId": "PBXAA000000010030065"
}



Sample Request for Drop-Off to CBDS with Generic Label (US & UK Outbound)

The following is a sample request for either a US or UK Outbound shipment that uses the Drop-Off to CBDS with Generic Label solution. The API prints a generic label the merchant uses to bring the parcel to the CBDS Hub.

Sample Request for Drop-Off to CBDS US & UK with Generic Label
curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 12,
            "height": 4,
            "width": 2,
            "unitOfMeasurement": "in"
        },
        "weight": {
            "unitOfMeasurement": "Lb",
            "weight": "30"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "resolution": "DPI_203",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "CARRIER_FACILITY_ID",
        "value": "GB_GEODIS_GBA"
    },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_GENERICLABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "GBP"
        },
        "customsItems": [ {
            "description": "Dish Towel 100% Cotton",
            "hSTariffCode": "6302600010",
            "hSTariffCodeCountry": "US",
            "itemId": "24d",
            "quantity": 100,
            "unitPrice": 10,
            "url": "https://www.example.com/Flour-Sack-Dish-Towels-White"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "FMEUK24192"
    } ]
}'
Sample Response for Drop-Off to CBDS UK with Generic Label
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 12,
            "height": 4,
            "width": 2,
            "unitOfMeasurement": "in"
        },
        "weight": {
            "weight": 30,
            "unitOfMeasurement": "Lb"
        "valueOfGoods": 1000.0
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "baseCharge": 258.27,
        "totalCarrierCharge": 428.27,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "5",
            "maxEstimatedNumberOfDays": "10"
        },
        "currencyCode": "GBP",
        "totalDutyAmount": 170.00
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "contents": "https://.../f03fc9ca3d4346a1ba7ec4d87a4d63b8.pdf"
    } ],
    "shipmentOptions": [ {
        "name": "CARRIER_FACILITY_ID",
        "value": "GB_GEODIS_GBA"
    },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_GENERICLABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "GBP"
        },
        "customsItems": [ {
            "itemId": "24d",
            "description": "Dish Towel 100% Cotton",
            "quantity": 100,
            "unitPrice": 10.00,
            "url": "https://www.example.com/Flour-Sack-Dish-Towels-White",
            "hSTariffCode": "6302600010",
            "hSTariffCodeCountry": "US"
        } ]
    },
    "domesticShipmentDetails": { ... },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "FMEUK24192"
    } ],
    "parcelTrackingNumber": "PBXGA00169B75401F704",
    "shipmentId": "PBXGA00169B75401F704"
}



Sample Request for Drop-Off to CBDS (Canada Outbound)

The following is a sample request for a Canada Outbound shipment that uses the :ref:` Drop-Off with Final-Mile Label <cbds-drop-off-cbds-final-mile-solution>` solution. The API prints the final-mile label for delivery from the CBDS Hub to the final destination.

The value of the request’s DELIVERY_SOLUTION option depends on whether the merchant delivers the parcel to the hub or Pitney Bowes picks it up. For values, see this table. In this example, the merchant delivers the parcel to the hub.

Sample Request for Drop-Off to CBDS (Canada Outbound)
curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
     "fromAddress": {
          "name": "Ken Ondricka",
          "phone": "211-827-9406",
          "email": "Antonio72@gmail.com",
              "addressLines": [
              "77 Massachusetts Ave",
              "apt 2113"
          ],
          "cityTown": "Cambridge",
          "company": "Dickinson, Mertz and Wehner",
          "stateProvince": "ON",
          "postalCode": "L4W 5C7",
          "countryCode": "CA"
     },
     "toAddress": {
          "name": "Vincent Kirlin",
          "phone": "226-492-2999",
          "email": "Myrna_Wuckert91@yahoo.com",
          "addressLines": [
              "31st Ave NW"
         ],
          "cityTown": "Danbury",
          "stateProvince": "NY",
          "postalCode": "06810",
          "company": "Weber, Boyer and Gutmann",
          "countryCode": "US"
     },
     "parcel": {
          "weight": {
              "unitOfMeasurement": "lb",
              "weight": "16.01"
     },
          "dimension": {
              "unitOfMeasurement": "in",
              "length": "5",
              "width": "2",
             "height": "3"
     }
   },
    "customs": {
          "customsInfo": {
             "currencyCode": "CAD"
         },
          "customsItems": [
             {
                  "unitWeight": {
                  "unitOfMeasurement": "lb",
                  "weight": "16.01"
                 },
                  "itemId": "Com83602",
                  "url": "www.company.com",
                  "description": "description 1",
                  "quantity": 1,
                  "unitPrice": "400",
                  "originCountryCode": "US",
                  "hSTariffCode": "6302600010",
                  "hSTariffCodeCountry": "US"
              }
          ]
     },
      "rates": [
         {
                  "carrier": "PBI",
                  "serviceId": "PBXPS",
                  "parcelType": "PKG"
         }
      ],
      "references": [
          {
                  "name": "ORDER_NUMBER",
                  "value": "FMIUS22071"
          }
      ],
      "documents": [
         {
                  "type": "SHIPPING_LABEL",
                  "size": "DOC_4X6",
                  "fileFormat": "PDF",
                  "contentType": "URL",
                  "printDialogOption": "EMBED_PRINT_DIALOG"
          }
     ],
     "shipmentOptions": [
        {
                  "name": "SHIPPER_ID",
                  "value": "SHP81575"
        },
       {
                  "name": "DELIVERY_SOLUTION",
                  "value": "DROPOFF_FINALMILELABEL"
         }
     ]
  }



Sample Response for Drop-off to CBDS

The following is a sample response for drop-off to CBDS.

{
     "fromAddress": {
         "addressLines": [
               "77 Massachusetts Ave",
               "apt 2113"
         ],
         "cityTown": "Cambridge",
         "stateProvince": "ON",
         "postalCode": "L4W 5C7",
         "countryCode": "CA",
         "company": "Swaniawski - Breitenberg",
         "name": "Allen Schumm",
         "phone": "713-645-3257",
         "email": "Jovani_Bashirian@hotmail.com"
      },
     "toAddress": {
           "addressLines": [
               "31st Ave NW"
         ],
           "cityTown": "Danbury",
           "stateProvince": "NY",
           "postalCode": "06810",
           "countryCode": "US",
           "company": "Jaskolski LLC",
           "name": "Debbie Rosenbaum",
           "phone": "904-552-4168",
           "email": "Nikita15@gmail.com"
     },
     "parcel": {
           "dimension": {
           "length": 5,
           "height": 3,
           "width": 2,
           "unitOfMeasurement": "in"
     },
    "weight": {
           "weight": 16.01,
           "unitOfMeasurement": "lb"
      },
    "valueOfGoods": 400
      },
    "rates": [
       {
           "carrier": "PBI",
           "serviceId": "PBXPS",
           "parcelType": "PKG",
           "baseCharge": 9,
           "totalCarrierCharge": 10.35,
           "deliveryCommitment": {
               "minEstimatedNumberOfDays": "5",
               "maxEstimatedNumberOfDays": "9"
       },
           "currencyCode": "CAD",
           "surcharges": [
              {
                   "name": "FUEL",
                   "fee": 1.35
              }
          ]
       }
      ],
      "documents": [
         {
               "type": "SHIPPING_LABEL",
               "size": "DOC_4X6",
               "fileFormat": "PDF",
               "contentType": "URL",
               "printDialogOption": "EMBED_PRINT_DIALOG",
               "contents": "https://stg-labels.gcs.pitneybowes.com/e8e5f24e6d7b4be8bd576cc74c52aab1.pdf"
          }
      ],
       "shipmentOptions": [
           {
               "name": "SHIPPER_ID",
               "value": "SHP84202"
           },
        {
               "name": "DELIVERY_SOLUTION",
               "value": "DROPOFF_FINALMILELABEL"
         }
      ],
       "customs": {
           "customsInfo": {
               "currencyCode": "CAD"
            },
           "customsItems": [
              {
                   "itemId": "Com148481",
                   "description": "description 1",
                   "quantity": 1,
                   "unitPrice": 400,
                   "url": "www.company.com",
                   "unitWeight": {
                       "weight": 16.01,
                       "unitOfMeasurement": "lb"
              },
                   "originCountryCode": "US",
                   "hSTariffCode": "6302600010",
                   "hSTariffCodeCountry": "US"
           }
       ]
     },
     "domesticShipmentDetails": {
           "barCodeLabelNumber": "4200681092612901006014000013345922"
     },
       "references": [
         {
           "name": "ORDER_NUMBER",
           "value": "FMIUS192525"
          }
      ],
      "parcelTrackingNumber": "PBXGAFBA8C12974D30E0",
      "shipmentId": "PBXGAFBA8C12974D30E0"

}



Sample Request for Pickup to CBDS (Canada Outbound)

The following shows the sample request for pickups to CBDS Canada Outbound.

curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
      "fromAddress": {
          "name": "Mabel Aufderhar",
          "phone": "557-293-6523",
          "email": "Vidal.Keebler@gmail.com",
          "addressLines": [
          "77 Massachusetts Ave",
          "apt 2113"
          ],
          "cityTown": "Cambridge",
          "company": "Jones - Halvorson",
          "stateProvince": "ON",
          "postalCode": "L4W 5C7",
          "countryCode": "CA"
     },
      "toAddress": {
          "name": "Sharon O'Hara I",
          "phone": "754-749-3494",
          "email": "Laurel_Adams63@gmail.com",
          "addressLines": [
               "31st Ave NW"
          ],
          "cityTown": "Danbury",
          "stateProvince": "NY",
          "postalCode": "06810",
          "company": "Parker LLC",
          "countryCode": "US"
      },
      "parcel": {
          "weight": {
              "unitOfMeasurement": "lb",
              "weight": "16.01"
      },
      "dimension": {
              "unitOfMeasurement": "in",
              "length": "5",
              "width": "2",
              "height": "3"
           }
       },
      "customs": {
          "customsInfo": {
              "currencyCode": "CAD"
       },
       "customsItems": [
           {
              "unitWeight": {
                  "unitOfMeasurement": "lb",
                  "weight": "16.01"
              },
              "itemId": "Com135390",
              "url": "www.company.com",
              "description": "description 1",
              "quantity": 1,
              "unitPrice": "400",
              "originCountryCode": "US",
              "hSTariffCode": "6302600010",
              "hSTariffCodeCountry": "US"
             }
         ]
       },
       "rates": [
         {
              "carrier": "PBI",
              "serviceId": "PBXPS",
              "parcelType": "PKG"
           }
         ],
        "references": [
           {
              "name": "ReferenceNumber",
              "value": "FMIUS88525"
          }
         ],
         "documents": [
        {
              "type": "SHIPPING_LABEL",
              "size": "DOC_4X6",
              "fileFormat": "PDF",
              "contentType": "URL",
              "printDialogOption": "EMBED_PRINT_DIALOG"
         }
        ],
         "shipmentOptions": [
            {
              "name": "SHIPPER_ID",
              "value": "9028249789"
           },
           {
             "name": "DELIVERY_SOLUTION",
             "value": "PICKUP_FINALMILELABEL"
           }
       ]
   }



Sample Response for Pickup to CBDS Canada Outbound

The following is a sample response for pickup to CBDS Canada Outbound

{
    "fromAddress": {
         "addressLines": [
             "77 Massachusetts Ave",
             "apt 2113"
         ],
         "cityTown": "Cambridge",
         "stateProvince": "ON",
         "postalCode": "L4W 5C7",
         "countryCode": "CA",
         "company": "Jones - Halvorson",
         "name": "Mabel Aufderhar",
         "phone": "557-293-6523",
         "email": "Vidal.Keebler@gmail.com"
 },
    "toAddress": {
         "addressLines": [
             "31st Ave NW"
         ],
         "cityTown": "Danbury",
         "stateProvince": "NY",
         "postalCode": "06810",
         "countryCode": "US",
         "company": "Parker LLC",
         "name": "Sharon O'Hara I",
         "phone": "754-749-3494",
         "email": "Laurel_Adams63@gmail.com"
 },
    "parcel": {
         "dimension": {
         "length": 5,
         "height": 3,
         "width": 2,
         "unitOfMeasurement": "in"
  },
         "weight": {
             "weight": 16.01,
             "unitOfMeasurement": "lb"
  },
         "valueOfGoods": 400
  },
   "rates": [
      {
         "carrier": "PBI",
         "serviceId": "PBXPS",
         "parcelType": "PKG",
         "baseCharge": 9,
         "totalCarrierCharge": 9,
         "deliveryCommitment": {
             "minEstimatedNumberOfDays": "5",
             "maxEstimatedNumberOfDays": "9"
      },
         "currencyCode": "CAD"
      }
   ],
   "documents": [
      {
         "type": "SHIPPING_LABEL",
         "size": "DOC_4X6",
         "fileFormat": "PDF",
         "contentType": "URL",
         "printDialogOption": "EMBED_PRINT_DIALOG",
         "contents": "https://stg-labels.gcs.pitneybowes.com/0cfe2dc539924ba5adaf8bb19a30e9e2.pdf"
      }
   ],
   "shipmentOptions": [
      {
         "name": "SHIPPER_ID",
         "value": "9028249789"
      },
     {
         "name": "DELIVERY_SOLUTION",
         "value": "PICKUP_FINALMILELABEL"
     }
   ],
   "customs": {
         "customsInfo": {
             "currencyCode": "CAD"
     },
         "customsItems": [
           {
             "itemId": "Com135390",
             "description": "description 1",
             "quantity": 1,
             "unitPrice": 400,
             "url": "www.company.com",
             "unitWeight": {
                 "weight": 16.01,
                 "unitOfMeasurement": "lb"
           },
             "originCountryCode": "US",
             "hSTariffCode": "6302600010",
             "hSTariffCodeCountry": "US"
         }
     ]
    },
    "domesticShipmentDetails": {
       "barCodeLabelNumber": "4200681092612901006014000013355877"
    },
    "references": [
     {
         "name": "ReferenceNumber",
         "value": "FMIUS88525"
      }
    ],
     "parcelTrackingNumber": "PBXGAD29073FBEC5408A",
      "shipmentId": "PBXGAD29073FBEC5408A"
}



Sample Request that Specifies a SELLER_ID

The following shows the additionalAddresses array and the SELLER_ID option, which are required for marketplace shippers. A marketplace shipper uses the same SHIPPER_ID for all sellers and must specify an individual seller through the SELLER_ID and specify the seller’s address through the additionalAddresses array.

curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "additionalAddresses": [ {
        "addressType":"SELLER",
        "address": {
            "name": "Art Shop",
            "addressLines": [
                "31st Avenue East"
            ],
            "cityTown": "Shelton",
            "stateProvince":"CT",
            "postalCode": "06618",
            "company": "Art's Art",
            "countryCode": "US",
            "email": shop@example.com,
            "phone":"1234567890"
        }
    } ],
    "parcel": { ... },
    "rates": [ { ... } ],
    "documents": [ ... ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "SELLER_ID",
        "value": "00123987b"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "FIRSTMILE"
    } ],
    "customs": { ... },
    "references": [ ... ]
}'



Sample Request for CBDS US Outbound Hazmat

The following is a sample request for US Outbound shipment for clients shipping hazmat.

{
        "fromAddress": {
            "name": "Tomas Kassulke",
            "phone": "464-612-9881",
            "email": "Angie.Barrows@gmail.com",
            "addressLines": [
            "77 Massachusetts Ave",
            "apt 2113"
            ],
            "cityTown": "Cambridge",
            "company": "Fahey - Windler",
            "stateProvince": "MA",
            "countryCode": "US"
         },
        "toAddress": {
            "name": "Chad Hansen",
            "phone": "496-907-3203",
            "email": "Carmel.Johnston47@hotmail.com",
            "addressLines": [
                "31st Ave NW"
            ],
            "cityTown": "Danbury",
            "stateProvince": "NY",
            "postalCode": "L9P1A5",
            "company": "Hammes - D'Amore",
            "countryCode": "CA"
        },
        "parcel": {
            "weight": {
                "unitOfMeasurement": "Lb",
                "weight": "16.01"
        },
        "dimension": {
            "unitOfMeasurement": "in",
            "length": "5",
            "width": "2",
            "height": "3"
          }
        },
        "customs": {
            "customsInfo": {
            "currencyCode": "USD"
        },
            "customsItems": [
            {
                "itemId": "54378DRE",
                 "description": "vintage floral-print patchwork long-sleeve cotton linen dress with pockets",
                 "quantity": 2,
                 "unitPrice": 100.00,
                 "url": "https://www.example.com/shop/women/clothing/dress/54378DRE",
                 "hSTariffCode": "610442",
                 "hSTariffCodeCountry": "US",
                 "hazmat": [
                     "batterytype-lithium"
                 ]
              }
           ]
         },
         "rates": [
             {
                    "carrier": "PBI",
                    "serviceId": "PBXPS",
                    "parcelType": "PKG"
              }
         ],
         "references": [
              {
                    "name": "ORDER_NUMBER",
                    "value": "FMIUS33864"
               }
          ],
          "documents": [
              {
                    "type": "SHIPPING_LABEL",
                     "size": "DOC_4X6",
                    "fileFormat": "PDF",
                    "contentType": "URL",
                    "printDialogOption": "EMBED_PRINT_DIALOG"
               }
          ],
          "domesticShipmentDetails": {
                "shipperTrackingNumber": "SHP203841Tr"
          },
            "shipmentOptions": [
                {
                    "name": "SHIPPER_ID",
                    "value": "9028249789"
                },
               {
                    "name": "CARRIER_FACILITY_ID",
                    "value": "US_GLOBAL_NJA"
                },
                {
                    "name": "DELIVERY_SOLUTION",
                    "value": "DROPOFF_CLIENTLABEL"
                }
              ]
        }



Sample Response for CBDS US Outbound Hazmat

The following is a sample response for US Outbound shipment for clients shipping hazmat.

{
    "fromAddress": {
        "addressLines": [
            "77 Massachusetts Ave",
            "apt 2113"
          ],
           "cityTown": "Cambridge",
           "stateProvince": "MA",
           "countryCode": "US",
           "company": "Fahey - Windler",
           "name": "Tomas Kassulke",
           "phone": "464-612-9881",
           "email": "Angie.Barrows@gmail.com"
      },
      "toAddress": {
           "addressLines": [
           "31st Ave NW"
      ],
           "cityTown": "Danbury",
           "stateProvince": "NY",
           "postalCode": "L9P1A5",
           "countryCode": "CA",
           "company": "Hammes - D'Amore",
           "name": "Chad Hansen",
           "phone": "496-907-3203",
           "email": "Carmel.Johnston47@hotmail.com"
      },
      "parcel": {
           "dimension": {
           "length": 5,
           "height": 3,
           "width": 2,
           "unitOfMeasurement": "in"
        },
           "weight": {
              "weight": 16.01,
              "unitOfMeasurement": "Lb"
      },
        valueOfGoods": 200.00
      },
      "rates": [
        {
            "carrier": "PBI",
            "serviceId": "PBXPS",
            "parcelType": "PKG",
            "baseCharge": 72.75,
            "totalCarrierCharge": 117.48,
            "deliveryCommitment": {
                "minEstimatedNumberOfDays": "4",
                "maxEstimatedNumberOfDays": "6"
             },
             "currencyCode": "USD",
             "totalDutyAmount": 36.00,
             "surcharges": [
                {
                  "name": "FUEL",
                  "fee": 8.73
                }
           ]
       }
      ],
      "documents": [
        {
               "type": "SHIPPING_LABEL",
               "size": "DOC_4X6",
               "fileFormat": "PDF",
               "contentType": "URL",
               "printDialogOption": "EMBED_PRINT_DIALOG"
        }
      ],
      "shipmentOptions": [
          {
               "name": "SHIPPER_ID",
               "value": "9028249789"
          },
          {
               "name": "CARRIER_FACILITY_ID",
               "value": "US_GLOBAL_NJA"
          },
          {
               "name": "DELIVERY_SOLUTION",
              "value": "DROPOFF_CLIENTLABEL"
          }
       ],
       "customs": {
            "customsInfo": {
                "currencyCode": "USD"
              },
            "customsItems": [
                {
                   "itemId": "54378DRE",
                   "description": "vintage floral-print patchwork long-sleeve cotton linen dress with pockets",
                   "quantity": 2,
                   "unitPrice": 100.00,
                   "url": "https://www.example.com/shop/women/clothing/dress/54378DRE",
                   "hSTariffCode": "610442",
                   "hSTariffCodeCountry": "US"
                 }
             ]
       },
       "domesticShipmentDetails": {
          "shipperTrackingNumber": "SHP203841Tr"
       },
       "references": [
            {
               "name": "ORDER_NUMBER",
               "value": "FMIUS33864"
            }
       ],
      "parcelTrackingNumber": "PBXGA0450C71AD9F683E",
      "shipmentId": "PBXGA0450C71AD9F683E"
    }

Error Codes

For common error codes specific to this API call, please see 13-Prefix Error Codes.

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.