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 CBDS Consolidation Centers in the U.S. to international destinations and performs checks to ensure parcels comply with international regulations prior to shipment. Invoking this API creates a post-paid CBDS shipment and submits parcel data for cross-border compliance checks.

Prerequisites

  • To use this API, your Developer Account must be enabled for CBDS. Please see Onboard with CBDS. To improve the accuracy of restriction screening, provide Pitney Bowes a category tree during onboarding.

  • Determine which solution the merchant uses for delivering the parcel to the Consolidation Center. See Delivery to the Consolidation Center.

    Depending on the solution, the API call will either print a label for delivery to the Consolidation Center or require that the merchant print a label ahead of time for delivery to the Consolidation Center. If the API requires the merchant to print the label, the merchant must provide the label’s tracking number when invoking this API. Failure to provide the tracking number will result in the parcel being unrecognized at the Consolidation Center.

Testing in Sandbox

When testing in Sandbox, use the Sandbox Client IDs on this page. You can use the Sandbox Client IDs with any Shipper ID in your Sandbox environment.

Things to Consider

  1. CBDS supports the following service classes. The available service classes for a merchant depend on the delivery agreement:

    Service ID
    Service Name
    Terms of Delivery
    Description
    PBXPS Standard DDP DDP This service is cost effective and offers full tracking.
    PBXUS Standard DDU DDU The service uses postal clearance at the country of destination.
    PBXPE Expedited DDP DDP This service is faster than Prepay Standard and costs more. It offers full tracking. Note: Expedited DDP does not support delivery to P.O. Boxes.
  2. The fromAddress, toAddress, and altReturnAddress objects require the following fields:

    • addressLines
    • cityTown
    • stateProvince. Required for Canadian addresses. Use the 2-letter province code.
    • postalCode
    • countryCode
    • name
  3. In the customInfo object, use only the currencyCode field. Set the value to USD, as shown here. The field is required.

    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        }
    }
    
  4. In the customItems.description field, provide detailed brand and item information. To facilitate assignment of the correct HS code, provide as much detail as possible. The following are example descriptions:

    "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"
    
  5. In the shipmentOptions array, set the following required shipment options:

    If the merchant prints the first-mile label before invoking this API, set these options as well:

  6. If the merchant prints the first-mile label before invoking this API, enter the label’s tracking number in the domesticShipmentDetails. This is required.

    Important

    Failure to provide the tracking number will result in the parcel being unrecognized at the Consolidation Center.

  7. The API response returns:

    • The estimated charges, which include the Transportation cost and, if applicable, the Importation costs.
    • A tracking number that tracks the parcel for the full journey, from the U.S. origin address to the international destination.
  8. If the merchant uses the API to print the first-mile label, the API response also returns the first-mile label. The label must be used within 25 days.

Request URIs

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

Query Parameter

Name Description
includeDeliveryCommitment If set to true, returns estimated transit time. Transit times is returned as number of days.
carrier Required. Set this to PBI.

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.

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

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 Address Object

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 Address Object

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 soldToAddress object. If importer’s address is the same as the final recipient, the toAddress and soldToAddress must match.

altReturnAddress Address Object

USPS, CBDS Only. Applies as follows:

  • USPS: If you are sending an international shipment through USPS and if you have set the NON_DELIVERY_OPTION shipment option to redirect, then enter the address that a returned parcel should go to.
  • CBDS: For a Create Shipment request, this is the address used to return a parcel from the CBDS Consolidation Center. If omitted, the fromAddress is used. The altReturnAddress is not returned in the response.
parcel Parcel Object 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 rates array can contain only one rates object.

documents Array[Documents Object]

Conditional. Defines the label, manifest, or other shipping document created by the API call.

This field is required except in the following cases:

  • This field does not apply to Rate Parcel requests.
  • This field does not apply to the Create CBDS Shipment request if the merchant prints the first-label prior to invoking the API.
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 SHIPPER_ID option is required. For any additional requirements for a carrier or service, please see the Things to Consider section on the carrier’s Create Shipment page.

        name String The name of the shipment option.
        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:

  • USPS: Required for shipments to international destinations or to APO/FPO/DPO, Territories/Possessions, or FAS.
  • CBDS: Required for all shipments.
  • FedEx: Required for shipments to international destinations and Puerto Rico.
  • UPS: Required for shipments to international destinations and Puerto Rico.
        customsInfo Customs Info Object Customs clearance information used to fill out a commercial invoice.
        customsItems Array[Customs Items Object]

Information about each commodity in the shipment, used for customs clearance.

The maximum number of objects in this array is 30.

domesticShipmentDetails Domestic Shipment Details Object 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 Address Object

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 toAddress.countryCode, with the exception of shipments to Canada and to U.S. satellite countries.

If the final recipient’s address is the same as the importer’s address, the entries in the soldToAddress object must match the entries in the toAddress object.

shipmentType String Return Labels Only. Set this to RETURN. Required for Expedited Returns and Standard Returns.
references Array[Object]

Merchant-defined values. Applies to the following:

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.

References Array in a CBDS Create Shipment Request

Use the references array to pass the shipper-generated order ID to Pitney Bowes. Pitney Bowes will include the ID in tracking files and invoices. The array is required, depending on the delivery solution and first-mile option:

Delivery Solution & First-Mile Option:  
PB End-to-End Solution with Bulk Pickup
Required
PB End-to-End Solution with Piece-Level Shipment Required
Client Drop-Off Solution with Drop-Off to PB Standard Required
Client Drop-Off Solution with Drop-Off to CBDS Optional but Recommended

The array takes the following object, where <order_ID> is the shipper-generated order ID:

{
    "name": "ORDER_NUMBER",
    "value": "<order_ID>"
}

Sample Requests

See the following examples:

PB End-to-End Sample Request

The following is a sample request for creating a CBDS shipment that prints the first-mile label. The response returns the first-mile label and the full-journey tracking number.

PB End-to-End Sample Request
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.005"
        },
        "dimension": {
            "unitOfMeasurement": "in",
            "length": "5",
            "width": "2",
            "height": "3"
        },
        "currencyCode": "USD"
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "Ins",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ]
        },{
            "specialServiceId": "ADSIG",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "0"
            } ]
        } ]
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "UP3456"
    } ],
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "brand": "brand1",
            "categories": [ {
                "categoryCode": "10203",
                "categoryNamePath": "CONSUMABLES AND GROCERY|BABY|BABY CARE|BABY CONSUMABLES|BABY FOOD",
                "categoryCodePath": "9785:8266:9798:9799:10203"
            } ],
            "description": "test123",
            "hSTariffCode": "610120",
            "hSTariffCodeCountry": "US",
            "identifiers": [ {
                "number": "123",
                "source": "none"
            } ],
            "itemDimension": {
                "length": 10,
                "height": 7,
                "width": 8,
                "unitOfMeasurement": "cm"
            },
            "itemId": "SKU123",
            "originCountryCode": "GB",
            "quantity": 2,
            "unitPrice": 400.88,
            "unitWeight": {
                "weight": 0.005,
                "unitOfMeasurement": "lb"
            },
            "url": "example.com"
        } ]
    }
}'
PB End-to-End Sample Response
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 5,
            "height": 3,
            "width": 2,
            "unitOfMeasurement": "in",
            "irregularParcelGirth": "0.0"
        },
        "weight": {
            "weight": 0.005,
            "unitOfMeasurement": "Lb"
        },
        "valueOfGoods": 801.76
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "Ins",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "50"
            } ],
            "fee": 2.2
        },{
            "specialServiceId": "ADSIG",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "0"
            } ],
            "fee": 6.4
        } ],
        "inductionPostalCode": "06810",
        "dimensionalWeight": {
            "weight": 0,
            "unitOfMeasurement": "OZ"
        },
        "baseCharge": 6.55,
        "totalCarrierCharge": 282.47,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "6",
            "maxEstimatedNumberOfDays": "9",
            "estimatedDeliveryDateTime": "2020-02-05",
            "guarantee": "NONE",
            "additionalDetails": "By end of Day"
        },
        "currencyCode": "USD",
        "destinationZone": 4,
        "totalDutyAmount": 144.32,
        "totalTaxAmount": 123
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "contentType": "URL",
        "contents": "https://.../usps/325584758/outbound/label/9d1da50f82734ab9d4a41d5ffb9a19b.pdf"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "UP3456"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "SKU123",
            "identifiers": [ {
                "number": "123",
                "source": "none"
            } ],
            "description": "test123",
            "quantity": 2,
            "unitPrice": 400.88,
            "url": "example.com",
            "unitWeight": {
                "weight": 0.005,
                "unitOfMeasurement": "lb"
            },
            "originCountryCode": "GB",
            "categories": [ {
                "categoryCode": "10203",
                "categoryNamePath": "CONSUMABLES AND GROCERY|BABY|BABY CARE|BABY CONSUMABLES|BABY FOOD",
                "categoryCodePath": "9785:8266:9798:9799:10203"
            } ],
            "itemDimension": {
                "length": 10,
                "height": 7,
                "width": 8,
                "unitOfMeasurement": "cm"
            },
            "brand": "brand1",
            "hSTariffCode": "610120",
            "hSTariffCodeCountry": "US"
        } ]
    },
    "parcelTrackingNumber": "UPGUS0164FC110CCA57",
    "shipmentId": "UPGUS00164FC10CCA57"
}

Client Drop-Off Sample Request

The following is a sample request for creating a CBDS shipment that returns a full-journey tracking number but no label. The merchant prints the first-mile label prior to the API call and passes in the first-mile tracking number when issuing the API.

Client Drop-Off Sample Request
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": "OZ",
            "weight": 24
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": "16",
            "width": "12",
            "height": "2"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "C12345"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_ELOVATIONS_KY"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "brand": "Acme Brand",
            "categories": [ {
                "categoryCode": "00065",
                "parentCategoryCode": "00857",
                "descriptions": [ {
                    "locale": "en_US",
                    "name": "Shirts",
                    "parentsName": [ "Clothing", "Men" ]
                } ],
                "categoryNamePath": "Clothing|Men|Shirts",
                "categoryCodePath": "01724:00857:00065"
            } ],
            "condition": "new",
            "description": "clothing men's shirt casual button-down slim fit cotton wrinkle-free single-needle construction",
            "hSTariffCode": "6205200010",
            "hSTariffCodeCountry": "CA",
            "itemDimension": {
                "length": 14.0,
                "height": 11.0,
                "width": 1.0,
                "unitOfMeasurement": "IN"
            },
            "itemId": "43953AE0",
            "identifiers": [ {
                "number": "841843",
                "source": "MPN"
            } ],
            "imageURL": [
                "http://www.example.com/shop/43953AE0/image01.png",
                "http://www.example.com/shop/43953AE0/image02.png"
            ],
            "manufacturer": "Acme Inc.",
            "originCountryCode": "US",
            "pricing": {
                "price": 45.00
            },
            "quantity": 1,
            "unitPrice": 45.00,
            "unitWeight": {
                "weight": 12,
                "unitOfMeasurement": "OZ"
            },
            "url": "http://www.example.com/shop/43953AE0"
        },
        { ... },
        ...
        ]
    },
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "USPS13600150468397",
        "carrier": "USPS"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123780"
    } ]
}'
Client Drop-Off Sample Response
{
    "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": 39.44,
        "totalCarrierCharge": 55.57,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "6",
            "maxEstimatedNumberOfDays": "9"
        },
        "currencyCode": "USD",
        "totalTaxAmount": 16.13
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "C12345"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_ELOVATIONS_KY"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "43953AE0",
            "identifiers": [ {
                "number": "841843",
                "source": "MPN"
            } ],
            "description": "clothing men's shirt casual button-down slim fit cotton wrinkle-free single-needle construction",
            "quantity": 1,
            "unitPrice": 45.00,
            "url": "http://www.example.com/shop/43953AE0",
            "unitWeight": {
                "weight": 12,
                "unitOfMeasurement": "OZ"
            },
            "originCountryCode": "US",
            "condition": "new",
            "manufacturer": "Acme Inc.",
            "categories": [ {
                "categoryCode": "00065",
                "parentCategoryCode": "00857",
                "descriptions": [ {
                    "locale": "en_US",
                    "name": "Shirts"
                } ],
                "categoryNamePath": "Clothing|Men|Shirts",
                "categoryCodePath": "01724:00857:00065"
            } ],
            "itemDimension": {
                "length": 14.0,
                "height": 11.0,
                "width": 1.0,
                "unitOfMeasurement": "IN"
            },
            "brand": "Acme Brand",
            "imageURL": [
                "http://www.example.com/shop/43953AE0/image01.png",
                "http://www.example.com/shop/43953AE0/image02.png"
            ],
            "pricing": {
                "price": 45.00
            },
            "hSTariffCode": "6205200010",
            "hSTariffCodeCountry": "CA"
        },
        { ... },
        ...
        ]
    },
    "domesticShipmentDetails": {
        "carrier": "USPS",
        "shipperTrackingNumber": "USPS13600150468397"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123780"
    } ],
    "parcelTrackingNumber": "UPGUS001580DCC1281C0",
    "shipmentId": "UPGUS001580DCC1281C0"
}

Sample CBDS Labels

End-to-End, USPS Label

The following is a sample label for a merchant who uses the PB End-to-End Solution and uses USPS for the first-mile option (Piece-Level Shipment option):

Sample CBDS label

Drop-Off, PB Standard Delivery Label

The following is a sample label for a merchant who uses the Client Drop-Off Solution and drops off to a PB Standard facility for the first-mile option:

Sample CBDS label

Error Codes

For common error codes specific to this API call, please see 130####.

For all error codes for the PB Shipping APIs, please see Error Codes.