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: name: The shipment option. value: The option’s value. 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 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 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.

 
 
 
 

• next
• previous |

© Copyright 2023, PB.