Create a CBDS Domestic Return Shipment

HTTP Request

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

Summary

This operation creates a CBDS Domestic Return. The operation prints a first-mile label for delivery from the local depot to a CBDS Hub. CBDS currently supports CA Domestic Returns and CA-US Returns.

For more information on CBDS, see Pitney Bowes Cross-Border Delivery Service (CBDS).

Prerequisite

To use this operation, a merchant must be enabled for CBDS Domestic Returns. To request enablement, merchants should contact their Pitney Bowes implementation managers or email their requests to either ClientSupportTechServices@pb.com or ShippingAPIBusinessDevelopment@pb.com.

Considerations

  1. The label must be used within 14 days.

  2. This operation requests a 4X6 label. If the 4X6 label size is not supported by the domestic carrier, the API returns the best-matched label size.

  3. Fuel surcharges are available through downloadable spreadsheets.

    CA Domestic Returns:

    Download the Fuel Surcharge spreadsheet

  4. Rates API is supported for CBDS Domestic Returns.

  5. This operation does not support in box return labels. The operation does not support putting labels inside the box.

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.

Request / Response Elements

Name

Data Type

Description

shipmentType

String

Recommended. Set this to the following: RETURN

fromAddress

Address Object

Required. The buyer address. The fromAddress object requires the following fields:

  • addressLines

  • cityTown

  • postalCode

  • countryCode

  • name

toAddress

Address Object

Required. The Seller/Retailer address. If you want the return shipped to a different location that the Seller/Retailer address, use the additionalAddresses array. The following fields are required:

  • addressLines

  • cityTown

  • postalCode

  • countryCode

  • company

  • name

additionalAddresses

Array[Object]

Prints a different return address on the label from the address entered in the toAddress field. If the Seller/Retailer’s address is different from the toAddress, enter the seller’s address here.

additionalAddresses.addressType

String

Set this to the following: SELLER

additionalAddresses.address

Address Object

The seller’s address. The object requires the following fields:

  • addressLines

  • cityTown

  • postalCode

  • countryCode

  • company

  • name

parcel

Parcel Object

Required. The parcel’s weight and dimensions.

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:

Field:

Value:

carrier

PBI

serviceId

One of the following:

  • PBDRCS: Domestic Return Standard Consolidated

  • PBDRS: Domestic Return Standard Per Piece

parcelType

PKG

documents

Array[Documents Object]

Required. Defines the label. The response returns the label as a URL. The array takes one documents object. The object requires the following fields and values:

Field:

Value:

type

SHIPPING_LABEL

size

DOC_4X6. If this size is not supported by the domestic carrier, the API will return the best-matched label size.

fileFormat

PDF

contentType

URL

printDialogOption

NO_PRINT_DIALOG

shipmentOptions

Array[Object]

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

Set the following shipment options:

  • SHIPPER_ID: Required. The merchant’s Shipper ID, which is found in the postalReportingNumber field returned by the Get Merchants API.

  • DELIVERY_SOLUTION: Required. The delivery solution for the shipment. Set this to: FIRSTMILE

  • CONTENT_VERIFICATION: Recommended. Indicates whether the contents of the parcel should be verified. Takes a value of true or false.

  • PRINT_RETURN_PACKSLIP: Recommended. Indicates whether the packing slip should be printed. Takes a value of true or false.

  • RETURN_DISPOSITION: Recommended. Indicates the disposition of the parcel. Set this to RETURN_TO_SELLER or DESTROY.

  • RETURN_REASON: Recommended. The reason for the return. Enter up to 100 characters.

customs

Object

Required. Customs information.

customs.customsInfo

Customs Info Object

Required. Customs clearance information for the commercial invoice.

customs.customsItems

Array[Customs Items Object]

Required. Customs clearance information for each commodity. The maximum number of objects in the array is 30.

domesticShipmentDetails

Object

RESPONSE ONLY. The first-mile label’s tracking number.

references

Array[Object]

Required. Each object in this array defines a reference field. Each object takes the following two elements, which take string values:

  • name: The name of the reference field.

  • value: The reference field’s value.

Set the following reference fields:

  • RMA_NUMBER: Required. The Return Merchandise Authorization (RMA) number. The number cannot have spaces.

  • ORDER_NUMBER: Recommended. The merchant-generated order ID. The ID cannot have spaces.

  • RETAILER_ORDER_NUMBER: Recommended. The retailer-generated order ID.

  • ORIGINAL_PARCEL_REFERENCE: Recommended. The merchant-generated parcel reference number of the original shipment.

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 Info Object for CBDS Domestic Returns

Name

Data Type

Description

currencyCode

String

Required. Set this to the following: USD

Customs Items Object for CBDS Domestic Returns

Name

Data Type

Description

description

String

Required. A detailed description of the commodity. Make the description as detailed as possible to facilitate assignment of the correct HS code.

Maximum length: 255 characters

itemId

String

Required. The merchant’s unique identifier for the commodity, such as the SKU or item code. The value might be used to verify the product during customs clearance. To avoid shipment delays, the value should be unique for individual variants of a product. To avoid problems processing the order data, make sure the value does not include leading or trailing spaces.

Maximum length: 50 characters

quantity

Integer

Required. Enter the total number of items of this type of commodity.

unitPrice

BigDecimal

Required. The price of one item of this type of commodity.

url

String

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

Maximum length: 1000 characters

Domestic Shipment Details Object for CBDS Domestic Returns

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.

Parcel Object

Name

Data Type

Description

weight

Object

Required. The parcel’s weight and unit of measure.

weight.weight

BigDecimal

Required. The parcel’s weight.

weight.unitOfMeasurement

String

Required. The unit of measure. For USPS shipments, set this to OZ.

Valid values, depending on the carrier:

  • OZ: Ounces

  • GM: Grams

  • G: Grams (CBDS only)

  • LB: Pounds (CBDS only)

  • KG: Kilograms (CBDS only)

dimension

Dimension Object

Defines the parcel’s dimensions. For the order of dimensions, see the Dimension Object.

Required for the following shipments:

  • PB Expedited using the Parcel Select service or using a Soft Pack Envelope

  • PB Standard

  • PB Presort

  • CBDS International Outbound from Canada

  • CBDS Domestic

  • CBDS Returns

  • CBDS Domestic Returns

Recommended for all shipments. Entering accurate dimensions helps avoid additional fees or parcels being undelivered.

currencyCode

String

ISO Currency Code. Use three uppercase letters, per ISO 4217. For example, for US Dollars use USD, for Canadian Dollars use CAD, and for Euros use EUR. For all currency codes, see https://www.iso.org/iso-4217-currency-codes.html.

valueOfGoods

BigDecimal

RESPONSE ONLY. For a CBDS shipment, the total value for the items in the shipment based on information sent in customs.customsItems.

Note

Do not send this field in a request. It will be ignored. The correct value will be sent in the response, based on the information you sent in customs.customsItems array.

 

Sample Request

Sample Request for CBDS Domestic Returns
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 '
{
    "shipmentType": "RETURN",
    "fromAddress": {
        "name": "First Last",
        "addressLines": [
            "Street 1"
        ],
        "cityTown": "CITY",
        "stateProvince": "ON",
        "postalCode": "Postal 1",
        "countryCode": "CA"
    },
    "toAddress": {
        "name": "Retailer A",
        "addressLines": [
            "31st Avenue East"
        ],
        "cityTown": "City",
        "stateProvince": "ON",
        "postalCode": "POSTAL 2",
        "company": "Company Name",
        "countryCode": "CA",
        "email": "retailerA@yahoo.com",
        "phone": "12345678"
    },
    "additionalAddresses": [ {
        "addressType": "SELLER",
        "address": {
            "name": "Retailer A",
            "addressLines": [
                "31st Avenue East"
            ],
            "cityTown": "CITY1",
            "stateProvince": "ON",
            "postalCode": "POSTAL 2",
            "company": "Company Name",
            "countryCode": "CA",
            "email": "retailerA@yahoo.com",
            "phone": "12345678"
        }
    } ],
    "parcel": {
        "weight": {
            "unitOfMeasurement": "Lb",
            "weight": "16"
        },
        "dimension": {
            "unitOfMeasurement": "in",
            "length": "5",
            "width": "2",
            "height": "3"
        },
        "currencyCode": "CAD"
    },
     "customs": {
        "customsInfo": {
            "currencyCode": "CAD",
        },
        "customsItems": [ {
            "itemId": "commodity1",
            "description": "test123",
            "url": "www.GOStest.com",
            "unitPrice": "500.00",
            "quantity": "1"
        } ]
    },
      "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "NO_PRINT_DIALOG"
    } ],
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBDRCS",
        "parcelType": "PKG"
    } ],
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "MerchantOrder-1195"
    },{
        "name": "RETAILER_ORDER_NUMBER",
        "value": "1234567890"
    },{
        "name": "RMA_NUMBER",
        "value": "1234567877"
    },{
        "name": "ORIGINAL_PARCEL_REFERENCE",
        "value": "1234567899"
     } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
         "name": "CONTENT_VERIFICATION",
        "value": ""TRUE|FALSE"
    },{
        "name": "PRINT_RETURN_PACKSLIP",
        "value": ""TRUE|FALSE"
    },{
        "name": "RETURN_DISPOSITION",
        "value": "RETURN_TO_SELLER"
    },{
        "name": "RETURN_REASON",
        "value": "[RETURN REASON]"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "FIRSTMILE"
    } ]
    }
}'
Sample Response
{
    "shipmentType": "RETURN",
    "fromAddress": {
        "name": "First Last",
        "addressLines": [
            "Street 1"
        ],
        "cityTown": "CITY",
        "stateProvince": "ON",
        "postalCode": "Postal 1",
        "countryCode": "CA"
    },
    "toAddress": {
        "name": "Retailer A",
        "addressLines": [
            "31st Avenue East"
        ],
        "cityTown": "CITY",
        "stateProvince": "ON",
        "postalCode": "POSTAL 2",
        "company": "Company Name",
        "countryCode": "CA",
        "email": "retailerA@yahoo.com",
        "phone": "12345678"
    },
    "additionalAddresses": [ {
        "addressType": "SELLER",
        "address": {
            "name": "Retailer A",
            "addressLines": [
                "31st Avenue East"
            ],
            "cityTown": "CITY1",
            "stateProvince": "ON",
            "postalCode": "POSTAL 2",
            "company": "Company Name",
            "countryCode": "CA",
            "email": "retailerA@yahoo.com",
            "phone": "12345678"
        }
    } ],
    "parcel": {
        "weight": {
            "unitOfMeasurement": "Lb",
            "weight": "16"
        },
        "dimension": {
            "unitOfMeasurement": "in",
            "length": "5",
            "width": "2",
            "height": "3"
        },
        "currencyCode": "CAD",
        "valueOfGoods": 801.76
        },
        "customs": {
        "customsInfo": {
            "currencyCode": "CAD",
        },
        "customsItems": [ {
            "itemId": "commodity1",
            "description": "test123",
            "url": "www.GOStest.com",
            "unitPrice": "500.00",
            "quantity": "1"
        } ]
    },
       "domesticShipmentDetails": {
        "shipperTrackingNumber": "7624003CPC0000042004Z",
        "barCodeLabelNumber": "7624003CPC0000042004Z"
    },
       "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "NO_PRINT_DIALOG",
        "contents": "<url to pdf>"
    } ],
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBDRCS",
        "parcelType": "PKG",
        "baseCharge": 26.88,
        "totalCarrierCharge": 26.88,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "6",
            "maxEstimatedNumberOfDays": "10"
        },
        "currencyCode": "CAD",
        "destinationZone": 1.0
     }],
       "references": [ {
        "name": "ORDER_NUMBER",
        "value": "MerchantOrder-1195"
    },{
        "name": "RETAILER_ORDER_NUMBER",
        "value": "1234567890"
    },{
        "name": "RMA_NUMBER",
        "value": "1234567877"
    },{
        "name": "ORIGINAL_PARCEL_REFERENCE",
        "value": "1234567899"
     }
     ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "0123456789"
    },{
        "name": "CONTENT_VERIFICATION",
        "value": "TRUE|FALSE"
    },{
        "name": "PRINT_RETURN_PACKSLIP",
        "value": "TRUE|FALSE"
    },{
        "name": "RETURN_DISPOSITION",
        "value": "RETURN_TO_SELLER"
    },{
        "name": "RETURN_REASON",
        "value": "[RETURN REASON]"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "FIRSTMILE"
    } ],
    "parcelTrackingNumber": "PBXGA001679CC18E3199",
    "shipmentId": "PBXGA001679CC18E3199"
}

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.