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 shipment is a post-paid shipment. The merchant’s delivery solution determines how the parcel arrives at the domestic CBDS Hub before international shipment and determines whether the API prints a shipping label. For all delivery solutions, the API returns an end-to-end tracking number from the origin address to the international destination.

Prerequisite

To ship with International Outbound, a merchant must be enabled. To request enablement, merchants must contact their PB implementation managers or email their requests to either ClientSupportTechServices@pb.com or ShippingAPIBusinessDevelopment@pb.com. During enablement, a merchant chooses one of the delivery solutions described below. The solution determines whether this API prints a label and determines how parcels arrive at the CBDS Hub.

Delivery Solutions for International Outbound

CBDS offers the following delivery solutions for International Outbound, depending on the country of origin:

Solution

Origin Country

Description

Piece-Level Shipment

U.S.

The API prints a USPS label for delivery to a CBDS Hub. For the first-mile, either USPS picks up the parcel or the merchant delivers the parcel to a USPS facility.

Bulk Pickup

U.S.

The API prints a PB Standard label. Pitney Bowes picks up the parcel. This solution is available for merchants who ship more than 200 parcels a day.

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. For the first-mile, the merchant delivers the parcel to a PB Standard facility. Do not enter a Client ID when using this solution. Doing so throws an error.

Drop-Off to CBDS

U.S., UK

The API does not print a label. The merchant prints the first-mile label prior to invoking the API. When invoking the API, the merchant provides the label’s tracking number. For the first-mile, the merchant delivers the parcel to a CBDS Hub.

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

  • Failure to provide the tracking number when invoking the API will result in the parcel being unrecognized at the CBDS Hub.

Drop-Off to CBDS with Generic Label

UK

The API prints a generic label the merchant uses when delivering the parcel to a CBDS Hub. For the first-mile, the merchant delivers the parcel to the CBDS Hub. When calling the API, the merchant provides the tracking number from the generic label. Failure to provide the tracking number will result in the parcel being unrecognized at the CBDS Hub.

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. For the first-mile, the merchant delivers the parcel to a CBDS Hub. The merchant attaches the final-mile label prior to delivery to the hub.

Considerations

  1. The CBDS page provides reference information for using CBDS with the ECommerce APIs.

  2. The merchant’s delivery solution determines whether the API returns a label. Before using this API, determine the merchant’s delivery solution.

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

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

  5. If the API returns a label, the label must be used within 25 days.

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 times 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. Some fields apply only to specific delivery solutions and are marked accordingly.

Name


Data Type

Description

fromAddress

Address Object

Required. The shipment’s origin address. If you want the label to display a different origin address from the one listed here, use the altReturnAddress field. The fromAddress object requires the following fields:

  • addressLines

  • cityTown

  • stateProvince: Required for Canadian addresses.

  • postalCode: Required if the API returns a label.

  • countryCode

  • name

toAddress

Address Object

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

  • addressLines

  • cityTown

  • stateProvince: Required for Canadian addresses.

  • postalCode: Required if the API returns a label. See also: Rules for Destination Postal Codes

  • countryCode

  • name

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 your returns, use this object to enter the address for your returns. Failure to do so would result in returns going to the wrong address. The altReturnAddress object requires the following fields:

  • addressLines

  • cityTown

  • stateProvince: Required for Canadian addresses.

  • postalCode: Required if the API returns a label.

  • countryCode

  • name

parcel

Parcel Object

Required. The parcel’s weight and dimensions.

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. For U.S. Outbound, the available classes further 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:

Set the following options, depending on the delivery solution:

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

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

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

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

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

hazmats

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 (Canada Outbound)

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


Sample Request to Return a USPS Label

The following is a sample request for the Piece-Level Shipment delivery solution. The request returns a USPS label, as shown below after the sample response.

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"
    } ],
    "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"
    } ],
    "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

The following sample request is used for both the Bulk Pickup and Drop-Off to PB Standard delivery solutions. For a sample label, see the sample label after the request and response.

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"
    } ],
    "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"
    } ],
    "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, which is returned for the Bulk Pickup and Drop-Off to PB Standard delivery 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. You must print the first-mile label prior to the API call. When making the API call, you must pass the label’s tracking number through the domesticShipmentDetails object. The request does not return a label.

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_ELOVATIONS_KY"
    } ],
    "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_ELOVATIONS_KY"
    } ],
    "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)

Merchants who use the Drop-Off to CBDS solution for the UK Hub have two options:

  • Print the first-mile label before invoking the API. See this sample request.

  • Use the API to print a generic first-mile label the merchant will use to bring the parcel to the UK Hub. See this sample request.

Sample UK Drop-Off Request that Inputs Tracking Number

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

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"
    } ],
    "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"
    } ],
    "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 UK Drop-Off Request that Prints Generic Label

Merchants who use the Drop-Off to CBDS solution for the UK Hub have the option of using the API to print a generic label the merchant will then use to bring the parcel to the UK 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"
    } ],
    "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"
    } ],
    "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)

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"
    } ],
    "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"
    } ]
}'


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.