Create a PB Cross-Border Delivery Service Shipment¶
HTTP Request¶
POST /v1/shipments?carrier=PBI
Summary¶
PB Cross-Border Delivery Service (CBDS) provides shipping from domestic Consolidation Centers to international destinations and uses shipper-supplied data to ensure parcels comply with international regulations prior to shipment. Invoking this API creates a post-paid CBDS shipment and provides an end-to-end tracking number.
CBDS provides outbound international shipping from the U.S. and the United Kingdom.
Prerequisites¶
The shipper must onboard with CBDS.
Testing in Sandbox¶
To test this API in Sandbox, use the Sandbox Client IDs listed on the Delivery Solution page. You can use the Sandbox Client IDs with any Shipper ID in your Sandbox environment.
Considerations¶
The shipper’s delivery solution determines whether the API returns a label. The delivery solution is chosen during onboarding.
Delivery Solution
Does the API Return a Label?
YES. The API returns a PB Standard label.
Piece-Level Shipment
(Available for U.S. Outbound only)YES. The API returns a USPS label.
Drop-Off to PB Standard
(Available for U.S. Outbound only)YES. The API returns the PB Standard label that Pitney Bowes will use to transport the parcel from a PB Standard facility to the CBDS Consolidation Center. The shipper is responsible for delivery to the PB Standard facility.
NO. Before invoking the API, the shipper must print a label for delivery to the CBDS Consolidation Center. The shipper supplies the label’s tracking number when invoking the API.
Note
Failure to provide the tracking number will result in the parcel being unrecognized at the Consolidation Center.
The
fromAddress
,toAddress
, andaltReturnAddress
objects require the following fields:addressLines
cityTown
stateProvince
. Required for Canadian addresses. Use the 2-letter province code.postalCode
. Required if the API returns a label. However, this field is always recommended.countryCode
name
The
altReturnAddress
is required if the fromAddress is the wrong address for your returns. Specify the return address in thealtReturnAddress
object.Important
By default, returns from the Consolidation Center are sent to the fromAddress. If that is not the correct return address, specify the correct return address in altReturnAddress. Failure to do so will result in a parcel being returned to the wrong address.
The supported service classes depend on the country of origin (as shown below), the shipping lane, and the merchant’s delivery agreement.
U.S. outbound supports the following service classes:
PBXPS
: Standard DDPPBXUS
: Standard DDUPBXPE
: Expedited DDP
UK outbound supports the following service class:
PBXPS
: Standard DDP
Canada outbound supports the following service class:
PBXPS
: Standard DDP
Do not pass a special service in the request. If you do, the service will be ignored. Note that the response might return the DelCon special service, which is a no-charge service.
In the
shipmentOptions
array, set the following options, depending on the delivery solution:Shipment Option
Required for:
All solutions
Solutions that print a PB Standard label
Solutions that print a PB Standard label
Bulk Pickup solution,
All Drop-Off solutionsThe
customs.customsInfo
object requires thecurrencyCode
field. For U.S. outbound, setcurrencyCode
toUSD
. For UK outbound, setcurrencyCode
toGBP
. For Canada outbound, setcurrencyCode
toCAD
.The API does not use the other fields in the
customs.customsInfo
object. If you pass them, they will be ignored.In the
customs.customsItems
array’sdescription
field, provide as much detail as possible about the item and brand in order 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"
If shipping a HAZMAT-flagged item, enter the applicable HAZMAT classifications in the
customs.customsItems
array’shazmats
field. See How Does CBDS Handle HAZMAT-flagged Items?If using the Drop-Off to CBDS solution, pass the first-mile label’s tracking number through the
domesticShipmentDetails
object.Important
Failure to provide the tracking number will result in the parcel being unrecognized at the CBDS Consolidation Center.
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 Consolidation Center.
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
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/shipments?carrier=PBI
Query Parameter¶
Name |
Description |
---|---|
carrier |
Required. Set this to |
includeDeliveryCommitment |
Required. If set to true, returns estimated transit time. Transit times is returned as number of days. Valid values:
|
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 |
X-PB-TransactionId |
Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens ( Important: Ensure this is unique. |
X-PB-UnifiedErrorStructure |
Recommended. Set this to |
Request / Response Elements¶
The API call sends and receives a Shipment Object. The table below describes all possible fields in a Shipment Object.
Important
Some fields in the Shipment Object do not apply to this operation.
Name |
Data Type |
Description |
---|---|---|
fromAddress |
Required. Origin address. If you want a different address to appear on the label from the one listed here, see How do I print a return address that is different from the origin address? |
|
toAddress |
Required. Destination address. FedEx, UPS: If you are shipping with FedEx or UPS to Puerto Rico or an international destination, and if the importer is different from the final recipient, this is the address of the importer. Enter the recipient’s address in the |
|
altReturnAddress |
PB Expedited, CBDS Only. Sets the address for parcel returns. Use this in the following situations:
|
|
parcel |
Required. Contains physical characteristics of the parcel. |
|
rates |
Array[Rates Object] |
Required. Specifies the carrier, service, parcel, and other information. In a response, this field also contains the service charges. Important: In a request, the |
documents |
Array[Documents Object] |
Conditional. Defines the label, manifest, or other shipping document created by the API call. In a response, this array provides the URL or Base64 string for a document and in some cases can contain multiple objects. This field is required, except in the following cases:
|
shipmentOptions |
Array[Object] |
Required. Each object in this array defines a shipment option. Specify each option as a name-value pair in the array. The |
shipmentOptions.name |
String |
The name of the shipment option. |
shipmentOptions.value |
String |
The value of the shipment option. |
customs |
Object |
Conditional. For shipments that use customs forms, this object contains the customs information. This field is required for the following carriers in the following situations:
|
customs.customsInfo |
Customs clearance information for the commercial invoice. When using the Customs Info Object, make sure to include the fields marked Required. |
|
customs.customsItems |
Array[Customs Items Object] |
Customs clearance information for each commodity. When using the Customs Items Object, make sure to include the fields marked Required. The maximum number of objects in this array is 30. |
domesticShipmentDetails |
CBDS Only. Required if the merchant prints the first-mile label prior to invoking the Create CBDS Shipment API. This object contains information about the first-mile leg of the shipment. |
|
soldToAddress |
FedEx, UPS Only. The final recipient of a the shipment. Required for a shipment from the U.S. to Puerto Rico or to an international destination. Otherwise optional. This address must match the If the final recipient’s address is the same as the importer’s address, the entries in the |
|
shipmentType |
String |
Return Labels Only. Set this to |
references |
Array[Object] |
PB Standard, CBDS Only. Conditional. The merchant’s reference fields. Each object in the array includes a name-value pair that defines a reference field. This array applies only to the following two carriers:
To pass references for carriers other than the above, see Reference Fields. |
references.name |
String |
PB Standard, CBDS Only. The name of the reference field. |
references.value |
String |
PB Standard, CBDS Only. The value for the reference field. |
hazmatDetails |
PB Standard Only. If shipping hazardous materials with PB Standard, use this object. |
|
carrierPayments |
FedEx, UPS Only. Indicates that one or more of the shipment costs should be charged to a third-party account. |
|
shipmentId |
String |
RESPONSE ONLY. Unique identifier for the shipment, generated by the system in response to shipment purchase. |
parcelTrackingNumber |
String |
RESPONSE ONLY. Tracking number assigned to the shipment by the system. |
Categories Object¶
Use the customs.customsItems.categories
array only if the merchant has provided Pitney Bowes a category tree. Otherwise, do not use the array. The array takes an object with the fields described below. For examples of the categories
array, see the Sample Requests further down on this page.
Name |
Data Type |
Description |
---|---|---|
categoryCode |
String |
Required. The item’s category identifier based on the product categories agreed on with Pitney Bowes. The maximum length is 50 characters. |
parentCategoryCode |
String |
Parent category of the item’s category identifier, based on the merchant product categories agreed on with Pitney Bowes. Maximum 50 characters. |
descriptions |
Array[Object] |
The description of the category. You can include multiple objects for descriptions in multiple languages. |
descriptions.locale |
String |
The language used for the category description. For example, |
descriptions.name |
String |
The category description. The maximum length is 255 characters. This field is required by the |
descriptions.parentsNames |
Array[String(255)] |
The tree of parent names to reach this category. |
categoryNamePath |
String |
Hierarchical path to the category represented by the category name of each level, concatenated with a pipe ( CONSUMABLES AND GROCERY|BABY|BABY CARE|BABY CONSUMABLES|BABY FOOD
|
categoryCodePath |
String |
Hierarchical path to the category represented by the category ID of each level, concatenated with a colon delimiter. For example: 9785:8266:9798:9799:10203
|
categorySiteId |
String |
The category site ID if the eBay category is referred. |
Domestic Shipment Details Object¶
Use the domesticShipmentDetails
object when using the Drop-Off to CBDS solution. Pass the first-mile label’s tracking number, as shown in the following example for a US Outbound shipment:
"domesticShipmentDetails": {
"shipperTrackingNumber": "USPS13600150468398",
"carrier": "USPS"
}
The object takes the following fields:
Name |
Data Type |
Description |
---|---|---|
shipperTrackingNumber |
String |
Required. The tracking number for the domestic leg of the shipment. |
carrier |
String |
The carrier for the domestic leg of the shipment. Possible values include: |
dcAddress |
The origin address for the domestic leg of the shipment. The parcel is shipped from this address to the CBDS Consolidation Center. |
References Array in a CBDS Shipment¶
Use the references
array to pass shipper-generated references. Pitney Bowes includes the values in tracking files and invoices. Each object in the array contains a name-value pair that defines a reference field, as shown here:
"references": [ {
"name": "ORDER_NUMBER",
"value": "<order_ID>"
},{
"name": "ReferenceNumber",
"value": "<ref_number>"
} ]
The array is recommended for all delivery solutions but is required as shown in the table below. The array defines the following reference fields:
Name |
Value |
Required for these Solutions |
---|---|---|
|
The shipper-generated order ID. |
|
|
The shipper-generated reference number. |
|
Sample Requests¶
This section provides the following sample requests:
For this solution: |
See this example: |
---|---|
Bulk Pickup |
|
Piece-Level Shipment |
|
Drop-Off to PB Standard |
|
Drop-Off to CBDS (U.S. Outbound) |
|
Drop-Off to CBDS (UK Outbound) |
|
Drop-Off to CBDS (Canada Outbound) |
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.
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"
} ]
}'
{
"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"
} ]
},
"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 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.
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": [ {
"categories": [ {
"categoryCode": "10203",
"categoryNamePath": "WOMEN|CLOTHING|DRESSES|FLORAL"
} ],
"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"
} ]
}'
{
"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",
"categories": [ {
"categoryCode": "10203",
"categoryNamePath": "WOMEN|CLOTHING|DRESSES|FLORAL",
"categoryCodePath": "9785:8266:9798:9799:10203"
} ],
"hSTariffCode": "610442",
"hSTariffCodeCountry": "US"
} ]
},
"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 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.
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": "USPS13600150468398",
"carrier": "USPS"
},
"references": [ {
"name": "ORDER_NUMBER",
"value": "123456"
} ]
}'
{
"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": "USPS13600150468398"
},
"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 Consolidation Center 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 Consolidation Center. 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.
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"
} ]
}'
{
"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 Consolidation Center have the option of using the API to print a generic label the merchant will then use to bring the parcel to the UK Consolidation Center.
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"
} ]
}'
{
"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"
} ]
},
"references": [ {
"name": "ORDER_NUMBER",
"value": "FMEUK24192"
} ],
"parcelTrackingNumber": "PBXGA00169B75401F704",
"shipmentId": "PBXGA00169B75401F704"
}
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"
}
},
"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"
} ]
},
"documents": [ {
"type": "SHIPPING_LABEL",
"size": "DOC_4X6",
"fileFormat": "PDF",
"contentType": "URL",
"printDialogOption": "EMBED_PRINT_DIALOG"
} ],
"rates": [ {
"carrier": "PBI",
"serviceId": "PBXPS",
"parcelType": "PKG"
} ],
"references": [ {
"name": "ORDER_NUMBER",
"value": "67707"
} ],
"shipmentOptions": [ {
"name": "SHIPPER_ID",
"value": "9024324564"
},{
"name": "CARRIER_FACILITY_ID",
"value": "CA_GLOBAL_ONA"
} ]
}'
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.