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.

Prerequisites

The shipper must onboard with CBDS.

Testing in Sandbox

To test this API in Sandbox, use the Sandbox Client IDs listed on this page. You can use the Sandbox Client IDs with any Shipper ID in your Sandbox environment.

Considerations

  1. The shipper’s delivery solution—chosen during onboarding with CBDS—determines whether the API returns a label:

    Delivery Solution
    Does the API Return a Label?
    End-to-End with Bulk Pickup Yes. The API returns a PB Standard pickup label.
    End-to-End with Piece-Level Shipment Yes. The API returns a USPS label.
    Drop-Off to PB Standard Yes. The API returns the label 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.
    Drop-Off to CBDS

    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.

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

  2. CBDS supports the following service classes, as described in the CBDS Service Classes table. The available classes depend on the merchant’s delivery agreement and on the shipping lane from the Consolidation Center.

    Service ID
    Service Name
    PBXPS Standard DDP
    PBXUS Standard DDU
    PBXPE Expedited DDP
  3. In the API call, 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
  4. The customs.customsInfo object must contain the currencyCode field and contain no other fields, as shown here:

    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        }
    }
    
  5. In the customs.customsItems array’s description 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"
    
  6. If shipping a HAZMAT-flagged item, enter the applicable HAZMAT classifications in the customs.customsItems array’s hazmats field. See How Does CBDS Handle HAZMAT-flagged Items?

  7. In the shipmentOptions array, set the following required options:

    If the delivery solution is Drop-Off to CBDS, you must also set the following:

  8. If the delivery solution is Drop-Off to CBDS, enter the first-mile label’s tracking number in domesticShipmentDetails.

    Important

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

  9. 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.
  10. If the API returns the first-mile label, the label must be used within 25 days.

Request URLs

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

PB Expedited, CBDS Only. Applies as follows:

  • PB Expedited: If you are sending an international shipment 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 Considerations 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:

  • PB Expedited: Required for shipments to international destinations. Conditional for shipments to APO/FPO/DPO, U.S. Territories, and FAS, as explained in this FAQ.
  • 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. In the Customs Info Object, make sure to include the fields marked Required.
        customsItems Array[Customs Items Object]

Information about each commodity in the shipment, used for customs clearance. In the Customs Items Object, make sure to include the fields marked Required.

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:

hazmatDetails Hazmat Details Object PB Standard Only. If shipping hazardous materials with PB Standard, use this object.
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 Shipment

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 takes the following object, where <order_ID> is the shipper-generated order ID:

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

The array is Required for the following delivery solutions:

And is recommended for:

Sample Requests

See the following example Create Shipment requests for the following delivery solutions:

End-to-End with Piece-Level Shipment

The following is a sample Create Shipment request for the End-to-End with Piece-Level Shipment delivery solution. The request returns a USPS label. For a sample label, see Sample USPS Label Returned by End-to-End Solution.

End-to-End Delivery 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": {
        "dimension": {
            "length": "12",
            "width": "5",
            "height": "10",
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 80,
            "unitOfMeasurement": "OZ"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "Ins",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "200"
            } ]
        } ]
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "contentType": "URL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "resolution": "DPI_203",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "USPSFM_1"
    } ],
    "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": "http://www.example.com/shop/women/clothing/dress/54378DRE"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ]
}'
End-to-End Delivery Sample Response
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 12,
            "height": 10,
            "width": 5,
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 80,
            "unitOfMeasurement": "OZ"
        },
        "valueOfGoods": 200.0
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBXPS",
        "parcelType": "PKG",
        "specialServices": [ {
            "specialServiceId": "DelCon",
            "inputParameters": [ {
                "name": "INPUT_VALUE",
                "value": "0"
            } ],
            "fee": 0.00
        } ],
        "inductionPostalCode": "36830",
        "dimensionalWeight": {
            "weight": 0.0,
            "unitOfMeasurement": "OZ"
        },
        "baseCharge": 42.22,
        "totalCarrierCharge": 89.87,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "5",
            "maxEstimatedNumberOfDays": "8"
        },
        "currencyCode": "USD",
        "destinationZone": 4,
        "totalDutyAmount": 16.20,
        "totalTaxAmount": 31.45
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_8X11",
        "fileFormat": "PDF",
        "contentType": "URL",
        "contents": "https://.../usps/325584758/outbound/label/9d1da50f82734ab9d4a41d5ffb9a19b.pdf"
        }
    ],
    "shipmentOptions": [ {
        "name": "HIDE_TOTAL_CARRIER_CHARGE",
        "value": "false"
    },{
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "ADD_TO_MANIFEST",
        "value": "false"
    },{
        "name": "FUTURE_SHIPMENT_DATE",
        "value": "2020-10-06 16:35:26.327"
    },{
        "name": "MINIMAL_ADDRESS_VALIDATION",
        "value": "false"
    },{
        "name": "SHIPPING_LABEL_RECEIPT",
        "value": "noOptions"
    },{
        "name": "PRINT_CUSTOM_MESSAGE_2",
        "value": "UPPBX0015B2A0E60EF73"
    },{
        "name": "CLIENT_ID",
        "value": "UP3456"
    } ],
    "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": "http://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"
}

For a sample label, see Sample USPS Label Returned by End-to-End Solution.

Drop-Off to CBDS

The following is a sample Create Shipment request for the Drop-Off to CBDS delivery solution. When using this solution, you must print the first-mile label prior to the API call and then pass its tracking number through the domesticShipmentDetails object when invoking the API. You also must include the CLIENT_FACILITY_ID and CARRIER_FACILITY_ID shipment options in the request.

Sample Request for Client Drop-Off with Drop-Off to CBDS
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": "CLIENT_ID",
        "value": "COFM_1"
    },{
        "name": "CLIENT_FACILITY_ID",
        "value": "0093"
    },{
        "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": "http://www.example.com/shop/43953AE0"
        } ]
    },
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "USPS13600150468398",
        "carrier": "USPS"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "123456"
    } ]
}'

The following is a sample response for the Drop-Off to CBDS delivery solution. The response does not include a label.

Sample Response for Client Drop-Off with Drop-Off to CBDS
{
    "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": "CLIENT_ID",
        "value": "COFM_1"
    },{
        "name": "CLIENT_FACILITY_ID",
        "value": "0093"
    },{
        "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": "http://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 USPS Label Returned by End-to-End Solution

The following is a sample label for the End-to-End with Piece-Level Shipment delivery solution:

Sample USPS Label Returned by End-to-End Solution

Sample Label Returned by the Drop-Off to PB Standard Solution

The following is a sample label for the Drop-Off to PB Standard delivery solution:

Sample Label Returned by Drop-Off to PB Standard Solution

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.