Create a CBDS Domestic Shipment

HTTP Request

POST /v1/shipments?carrier=PBI&includeDeliveryCommitment=true

Summary

Use this operation to ship with CBDS within Canada. The operation prints either a first-mile or final-mile label, depending on the shipment’s delivery solution. The shipment is a post-paid shipment. CBDS Domestic ships with the Domestic Standard Service, which uses a service ID of PBDS.

Note

This page describes domestic shipping within Canada. For other CBDS shipment types, see Create a Shipment.

Prerequisite

To ship with CBDS Domestic, a merchant must first be enabled. To request enablement, contact Pitney Bowes at either ClientSupportTechServices@pb.com or ShippingAPIBusinessDevelopment@pb.com, or contact the merchant’s Pitney Bowes implementation manager. During enablement, the merchant sets up one or more delivery solutions.

Delivery Solutions for CBDS Domestic

The delivery solution determines how parcels arrive at the CBDS Hub and what type of label the API prints:

Solution	Does the Create Shipment API Print a Label?	First-Mile Option	DELIVERY_SOLUTION
Drop-Off to Local Depot	Yes. The API prints a first-mile label for delivery from a local depot to the CBDS Hub.	The merchant delivers the parcel to the local depot.	FIRSTMILE
Drop-Off to CBDS with Final-Mile Label	Yes. The API prints the final-mile label for delivery from the CBDS Hub to the final destination.	The merchant delivers the parcel to the CBDS Hub. The merchant attaches the final-mile label prior to delivery to the hub.	DROPOFF_FINALMILELABEL
Bulk Pickup with Final-Mile Label	Yes. The API prints the final-mile label for delivery from the CBDS Hub to the final destination.	Pickup is available for high-volume shippers. Pitney Bowes picks it up the parcel for delivery to the CBDS Hub. The merchant attaches the final-mile label prior to delivery to the hub.	PICKUP_FINALMILELABEL

Considerations

1. The label must be used within 14 days.

2. You cannot use the Rates API with CBDS Domestic shipments.

3. Labels retrieved through URLs are available for 24 hours after creation.

4. Fuel charges are available as a downloadable spreadsheet. The following link downloads the most recent version of the spreadsheet:

   Download the Current Fuel Surcharge Spreadsheet

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 Parameters

Name	Description
carrier	Required. Set this to PBI.
includeDeliveryCommitment	Required. If set to true, returns estimated transit time. Transit time 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 as such. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

Name	Data Type	Description
fromAddress	Address Object	Required. The shipment’s origin address. The following fields are required: addressLines cityTown stateProvince: Use the 2-letter province code. postalCode countryCode name
toAddress	Address Object	Required. The shipment’s destination address. The following fields are required: addressLines cityTown stateProvince: Use the 2-letter province code. postalCode countryCode name
parcel	Object	Required. The parcel’s weight and dimensions.
parcel.weight	Object	Required. The parcel’s weight and unit of measure.
parcel.weight.weight	BigDecimal	Required. The parcel’s weight.
parcel.weight.unitOfMeasurement	String	Required. The weight unit of measure. Valid values: OZ: Ounces GM: Grams G: Grams LB: Pounds KG: Kilograms
parcel.dimension	Object	Required. Defines the parcel’s dimensions. For the order of dimensions, see the Dimension Object.
parcel.dimension.length	BigDecimal	Required. The longest dimension.
parcel.dimension.height	BigDecimal	Required. The second longest dimension.
parcel.dimension.width	BigDecimal	Required. The smallest dimension.
parcel.dimension.unitOfMeasurement	String	Required. The unit of measure. Valid values: IN: Inches CM: Centimeters
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: carrier: Set to PBI. serviceId: Set to PBDS. parcelType: Set to PKG.
documents	Array[Documents Object]	Required. Defines the label. The array takes one documents object. The object requires the following fields and values: type: Set to SHIPPING_LABEL. printDialogOption: Set to one of the following, as described here: EMBED_PRINT_DIALOG NO_PRINT_DIALOG size: Set to either DOC_4X6 (portrait orientation) or DOC_6X4 (landscape orientation). fileFormat and contentType: Set to one of the following valid combinations. Note that a PDF can be returned as either a URL or BASE64-encoded PDF. If the options you choose are not supported by the domestic carrier, the API might return different options from those you sent in the request. fileFormat contentType PDF PDF PNG URL BASE64 BASE64 Note In cases where a domestic carrier does not support a format or content type, the API returns the best-matched option for that carrier. This could mean, for example, that the API returns a PNG instead of a requested PDF.
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. The following options are required: SHIPPER_ID: Required. Enter the merchant’s Shipper ID, which is found in the postalReportingNumber field returned by the Merchants API. DELIVERY_SOLUTION: This option is not yet in Production but is coming soon. This option will be required and will be used to indicate which delivery solution to use from the values listed here. Important Do not include CLIENT_ID, CLIENT_FACILITY_ID, or CARRIER_FACILITY_ID
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 CAD.
customs.customsItems	Array[Customs Items Object]	Required. Commodity information.
domesticShipmentDetails	Object	RESPONSE ONLY. The printed label’s tracking number.
references	Array[Object]	This array passes optional merchant-generated reference fields. Pitney Bowes includes the values in tracking files and invoices. Each object in the array takes the following two elements, which take string values: name: The name of the reference field. value: The reference field’s value. You can set the following optional reference fields: ORDER_NUMBER: The merchant-generated order ID. The order ID cannot have spaces. ReferenceNumber: The merchant-generated reference number.
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 Domestic

Name	Data Type	Description
description	String	Required. A detailed description of the commodity, up to 255 characters.
itemId	String	Required. The merchant’s unique identifier for the commodity, such as the SKU or item code. Make sure the value does not include leading or trailing spaces. Maximum length: 50 characters
quantity	Integer	Required. The number of items of the commodity.
unitPrice	BigDecimal	Required. The price of one item of this type of commodity.

Domestic Shipment Details Object for CBDS Domestic

Name	Data Type	Description
shipperTrackingNumber	String	The tracking number for the domestic leg of the CBDS shipment.
barCodeLabelNumber	String	The tracking number for the domestic leg of the CBDS shipment. This number also appears in the shipperTrackingNumber field.

Sample Requests

This section provides sample requests for the different delivery solutions. For details on the solutions, see Delivery Solutions for CBDS Domestic, above on this page.

For this solution:	See this example:
Drop-Off to Local Depot	Sample Request for Drop-Off to Local Depot
Drop-Off to CBDS with Final-Mile Label	Sample Request for a Final-Mile Label
Bulk Pickup with Final-Mile Label	Sample Request for a Final-Mile Label

Sample Request for Drop-Off to Local Depot

This request uses the Drop-Off to Local Depot delivery solution. For details on the solution, see Delivery Solutions for CBDS Domestic above on this page.

Sample Request to Drop-Off to Local Depot

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": {
        "addressLines": [
            "2233 South Millway"
        ],
        "cityTown": "Mississauga",
        "stateProvince": "ON",
        "postalCode": "L5L 3H7",
        "countryCode": "CA",
        "name": "Jill Smith"
    },
    "toAddress": {
        "addressLines": [
            "323 1st St East"
        ],
        "cityTown": "Brooks",
        "stateProvince": "AB",
        "postalCode": "T1R 0G9",
        "countryCode": "CA",
        "name": "Bruce Green"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "LB",
            "weight": "0.95"
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": 8,
            "width": 4,
            "height": 6
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBDS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "CAD"
        },
        "customsItems": [ {
            "description": "vintage floral-print dress",
            "itemId": "4885-NJE",
            "originCountryCode": "CA",
            "quantity": 2,
            "unitPrice": 400,
            "url": "http://example.com/dresses/vintage/4885nje"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "1234-5678"
    } ]
}'

Sample Response

{
    "fromAddress": {
        "addressLines": [
            "2233 South Millway"
        ],
        "cityTown": "Mississauga",
        "stateProvince": "ON",
        "postalCode": "L5L 3H7",
        "countryCode": "CA",
        "name": "Jill Smith"
    },
    "toAddress": {
        "addressLines": [
            "323 1st St East"
        ],
        "cityTown": "Brooks",
        "stateProvince": "AB",
        "postalCode": "T1R 0G9",
        "countryCode": "CA",
        "name": "Bruce Green"
    },
    "parcel": {
        "dimension": {
            "length": 8.0,
            "height": 6.0,
            "width": 4.0,
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 0.95,
            "unitOfMeasurement": "LB"
        },
        "valueOfGoods": 800.00
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBDS",
        "parcelType": "PKG",
        "baseCharge": 11.42,
        "totalCarrierCharge": 14.19,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "3",
            "maxEstimatedNumberOfDays": "6"
        },
        "currencyCode": "CAD",
        "destinationZone": 1.0
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "EMBED_PRINT_DIALOG",
        "contents": "https://.../a60674f0644044459c29ab873ca89d2b.pdf"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "CAD"
        },
        "customsItems": [ {
            "itemId": "4885-NJE",
            "description": "vintage floral-print dress",
            "quantity": 2,
            "unitPrice": 400.00,
            "url": "http://example.com/dresses/vintage/4885nje",
            "originCountryCode": "CA"
        } ]
    },
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "329000000101",
        "barCodeLabelNumber": "329000000101"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "1234-5678"
    } ],
    "parcelTrackingNumber": "PBXGA654A00000FDBC0E",
    "shipmentId": "PBXGA654A00000FDBC0E"
}

Sample Request for a Final-Mile Label

The following sample request is used for both the Drop-Off to CBDS and Bulk Pickup solutions. For details on the solutions, see Delivery Solutions for CBDS Domestic above on this page.

Sample Request for a Final-Mile 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": {
        "addressLines": [
            "123 Caravelle Drive"
        ],
        "cityTown": "Mississauga",
        "stateProvince": "ON",
        "postalCode": "L4V 1K9",
        "countryCode": "CA",
        "name": "Alan Jones"
    },
    "toAddress": {
        "addressLines": [
            "31st Avenue East"
        ],
        "cityTown": "Brooks",
        "stateProvince": "AB",
        "postalCode": "T1R 0A4",
        "countryCode": "CA",
        "name": "Victoria Anderson"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "LB",
            "weight": "0.5"
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": "12",
            "width": "6",
            "height": "10"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBDS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "CAD"
        },
        "customsItems": [ {
            "itemId": "OLCom_255",
            "description": "satin pleated waist skirts",
            "url": "http://example.com/skirts",
            "unitPrice": "300",
            "quantity": "3",
            "originCountryCode": "CA"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "45729-a80w"
    } ]
}'

Sample Response

{
    "fromAddress": {
        "addressLines": [
            "123 Caravelle Drive"
        ],
        "cityTown": "Mississauga",
        "stateProvince": "ON",
        "postalCode": "L4V 1K9",
        "countryCode": "CA",
        "name": "Alan Jones"
    },
    "toAddress": {
        "addressLines": [
            "31st Avenue East"
        ],
        "cityTown": "Brooks",
        "stateProvince": "AB",
        "postalCode": "T1R 0A4",
        "countryCode": "CA",
        "name": "Victoria Anderson"
    },
    "parcel": {
        "dimension": {
            "length": 12.0,
            "height": 10.0,
            "width": 6.0,
            "unitOfMeasurement": "IN"
        },
        "weight": {
            "weight": 0.5,
            "unitOfMeasurement": "LB"
        },
        "valueOfGoods": 900.00
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBDS",
        "parcelType": "PKG",
        "baseCharge": 26.43,
        "totalCarrierCharge": 26.43,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "3",
            "maxEstimatedNumberOfDays": "6"
        },
        "currencyCode": "CAD",
        "destinationZone": 1.0
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "EMBED_PRINT_DIALOG",
        "contents": "https://.../690cf25e9eae4ea49abd9b8b4050f4ba.pdf"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "CAD"
        },
        "customsItems": [ {
            "itemId": "OLCom_255",
            "description": "satin pleated waist skirts",
            "quantity": 3,
            "unitPrice": 300.00,
            "url": "http://example.com/skirts",
            "originCountryCode": "CA"
        } ]
    },
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "7624003NGST0000042004Z",
        "barCodeLabelNumber": "7624003NGST0000042004Z"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "45729-a80w"
    } ],
    "parcelTrackingNumber": "PBXGA03A2C000DB5E84F",
    "shipmentId": "PBXGA03A2C000DB5E84F"
}

Error Codes

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.

 
 
 
 

• next
• previous |

© Copyright 2023, PB.