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 GEC-TechSupport@pb.com or ShippingAPIBusinessDevelopment@pb.com.

Considerations¶

The label must be used within 14 days.
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.
Fuel surcharges are available through downloadable spreadsheets.

CA Domestic Returns:

Download the Fuel Surcharge spreadsheet
Rates API is supported for CBDS Domestic Returns.
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:

name: The shipment option.
value: The option’s value.

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 Delivery 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.