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 ClientSupportTechServices@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 Standard label.

PICKUP_STANDARDLABEL

Drop-Off to PB Standard

U.S.

The API prints a PB Standard label for delivery from a PB Standard facility to a CBDS Hub. The label must include “Attn: PB Cross-Border” on Address Line 1. The merchant delivers the parcel to the PB Standard facility.

PICKUP_STANDARDLABEL

Drop-Off 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 to CBDS with Generic Label

UK

The API prints a generic label the merchant uses to deliver the parcel to the CBDS Hub.

  • DROPOFF_GENERICLABEL: Merchant delivers parcel to hub

  • PICKUP_GENERICLABEL: Pitney Bowes picks up parcel

Drop-Off 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 the parcel to 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.

  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 Type

Description

fromAddress

Address Object

Required. The shipment’s origin address. If the merchant wants the label to display a different origin address from the one listed here, use the altReturnAddress field. 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 if the API returns a label.

  • 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 if the API returns a label. 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 if the API returns a label.

  • 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: Standard DDP

  • PBXUS: Standard DDU

UK Outbound:

  • PBXPS: Standard DDP

Canada Outbound:

  • PBXPS: Standard 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 Standard label. Enter the merchant’s ID for access to CBDS.

  • CLIENT_FACILITY_ID: Conditional. Required for delivery solutions that print a PB Standard 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.

    • ReferenceNumber: Indicates the reference field is a merchant-generated reference number.

  • 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.

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 Standard Label

Drop-Off to PB Standard

Sample Request to Return a PB Standard Label

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

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

Drop-Off to CBDS (UK Outbound)

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

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

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

Drop-Off 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


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 Standard Label

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

Sample Request to Return a PB Standard 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 Standard 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 Standard Label

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

Sample PB Standard 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 (UK Outbound)

The following is a sample request for a 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 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": { ... },
    "toAddress": { ... },
    "altReturnAddress": { ... },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "Lb",
            "weight": "0.03"
        },
        "dimension": {
            "unitOfMeasurement": "in",
            "length": "5",
            "width": "7",
            "height": "6"
        }
    },
    "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": "CARRIER_FACILITY_ID",
        "value": "CA_GLOBAL_ONA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_FINALMILELABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "CAD"
        },
        "customsItems": [ {
            "itemId": "OLCom_973",
            "description": "shore bird canvas wall art for family room living room bedroom 12x12",
            "url": "www.example.com/olcom_973",
            "unitPrice": "500",
            "quantity": "1",
            "hSTariffCode": "6205200010",
            "hSTariffCodeCountry": "CA",
            "originCountryCode": "CA"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "67707"
    } ]
}'



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": [ ... ]
}'


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.