Create a CBDS Canada 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 Canada Domestic ships with the Domestic Standard Service, which uses a service ID of PBDS.

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

Prerequisite

To ship with CBDS Canada 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 Canada Domestic

The delivery solution determines how parcels arrive at the CBDS Hub and what type of label the API prints. Merchants can have multiple delivery solutions and can add delivery solutions by contacting their PB implementation managers. When issuing this API request, the merchant chooses the solution to use by passing a value through the DELIVERY_SOLUTION option in the shipmentOptions array. The table below gives the value to pass.

Solution

Does the Create Shipment API Print a Label?

First-Mile Option

In Create Shipment API set DELIVERY_SOLUTION to:

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 following maximums apply to CBDS Canada Domestic shipments:

    Maximum Weight:

    66 lbs

    Maximum Length:

    118 inches

    Maximum SUM of DIMs:

    173 inches

    Dim Factor: 166

    Maximum Value:

    $2,500

  2. This operation does not support Dangerous Goods.

  3. Fuel surcharges are available as a downloadable spreadsheet.

    To help you calculate the fuel surcharge for a CBDS Canada Domestic shipment, Pitney Bowes provides the following guide:

  4. A fee is assessed if the package is returned to the shipper from the U.S. hub. Possible reasons for this fee are listed here but are not limited to this list.

    • Damaged or leaking box

    • Empty box or unknown items shipper

    • Incorrect delivery address

    • Oversized/overweight beyond the limits of the shipping lane

    • Unknown items shipped

    • Unreadable barcode. For example, unable to be scanned or hand keyed by operator or poor-label quality

    • Buyer failed/denied party screening

  5. A parcel-level charge is added for Oversized Handling if the parcel exceeds the maximum dimensions/weight for the service and if Pitney Bowes must ship the parcel using a premium service. This charge is over and above the shipping rate for the parcel. The shipper’s rate card has the applicable dimensions. The limits are not assessed on first-mile cartons but on individual parcels.

  6. The API might return a different label format from the one you choose in the request. The API does so if the domestic carrier does not support the format you chose. The API returns the carrier’s best matched format.

  7. If you select to have the API return the label through a URL, the URL is available for 24 hours after you create the label.

  8. A label printed with this API must be used within 14 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 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: Enter both the first and last 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.

Maximum: 66 lbs

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.

Enter length as the longest dimension, height as the next longest, and width as shortest. If you enter dimensions differently, the API will reassign them. For more information, see Entering Dimensions.

Maximum SUM of DIMs: 173 inches

Dim Factor: 166

parcel.dimension.length

BigDecimal

Required. The longest dimension.

Maximum: 118 inches

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 combinations. Labels retrieved through URLs are available for 24 hours after creation.

    Note

    If the 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.

    fileFormat

    contentType

    PDF

    PDF
    PNG

    URL

    BASE64
    BASE64

shipmentOptions

Array[Object]

Required. Each object in this array defines a shipment option. Each object takes the following two fields, which take string values:

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: Required. Enter the value for the shipment’s delivery solution as specified in the Delivery Solution table above. Note: This option is not required for accounts created prior to April 2023 that use only one solution.

Important

Do not include the CLIENT_ID, CLIENT_FACILITY_ID, or CARRIER_FACILITY_ID shipment options in the API request.

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 Canada Domestic

For our Canada Domestic solution, Customs items are required for compliance regulations.

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.

url

String

Required. The commodity’s URL on the merchant site.

Domestic Shipment Details Object for Canada 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 Canada Domestic, above on this page.

For this solution:

See this example:

Drop-Off to Local Depot

Sample Request for Drop-Off for 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 for Local Depot

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

Sample Request for 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"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "FIRSTMILE"
    } ],
    "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 for Drop-Off to a Local Depot
{
    "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"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "FIRSTMILE"
    } ],
    "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. The value of the request’s DELIVERY_SOLUTION option depends on which solution. For the correct value to use, see the Delivery Solutions for Canada Domestic table on this page. In this example, the merchant uses the Drop-Off to CBDS solution.

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"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_FINALMILELABEL"
    } ],
    "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"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_FINALMILELABEL"
    } ],
    "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.