Create a PB Returns Label

HTTP Request

POST /v1/shipments

Summary

This operation creates a Pitney Bowes Returns label for a buyer to use if returning a parcel. The label is a post-paid label and incurs no charges unless used. The label contains a USPS-compliant barcode and can be tracked via the Tracking API. The label also contains a PB Returns barcode. Shippers also have the option of printing a third, custom barcode:

The API provides the option to create a QR code instead of a label. The buyer uses the QR code to print the label on a printer or at a Post Office or other shipping facility. You can use the Carrier Facilities API to provide the buyer with nearby facilities that print labels. A buyer who has a printer can print the label by entering the QR code’s Label ID at the USPS Label Broker website.

Prerequisite

To create a PB Returns label, a merchant must first onboard with PB Returns. When a merchant onboards, the merchant is enrolled with a PB Returns facility and receives a set of PB Returns IDs.

Considerations

1. PB Returns is a post-paid service. Postage is not charged at the time of label creation.

2. PB Returns are supported for domestic shipments only.

3. PB Returns use the Parcel Select Return service and the package parcel type.

4. PB Returns do not support special services.

5. This operation prints either a shipping label or QR code.

6. If you choose to create a QR code, you can use the Carrier Facility API to provide the buyer with nearby USPS facilities that accept QR codes either with USPS or in the Pitney Bowes Drop Off Network.

7. To add an optional custom barcode at the bottom of the label, set the custom barcode parameters in the documents.customerData.labelDetails array, as described below.

8. Merchants can also set up custom functions, such as printing additional text or applying business rules. To do so, a merchant must set up the function in advance with the PB implementation manager. To add a custom function when printing a label, set the function’s parameters in the documents.customerData object.

9. To optionally apply minimal address validation to the fromAddress, which is the address of the buyer who is returning the item, set MINIMAL_ADDRESS_VALIDATION to true in the shipmentOptions array. For a comparison of complete and minimal address validation, see this FAQ.

10. If you choose to retrieve the label through a URL, the label is available for 24 hours after label creation.

11. The API returns a parcel tracking number you can use to track the label via the Tracking API.

12. If the API call returns the HTTP 500 Internal Server Error, see these troubleshooting steps.

    For other errors, do not resubmit the request without first checking whether the label was created through the Retry API.

13. PB Returns labels are not manifested.

---

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/shipments
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/shipments

Request Headers

Name	Description
Authorization	Required. OAuth token generated using the OAuth Token API.
Content-Type	Required. The media type of the request entity. Set this to application/json.
Accept-Language	Language and country code. Default: en-US
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 a unique ID.
X-PB-Use-Merchant-Logo	If a merchant is configured to print a custom logo on PB Returns labels, the custom logo is printed on the label by default. You can optionally leave the logo off a given label by setting this header to false. To be configured to print custom logos on PB Returns labels, merchants should contact their Pitney Bowes implementation teams.

Request Elements

Required fields are marked Required. All other fields are optional.

Name	Data Type	Description
shipmentType	String	Required. Set to RETURN
fromAddress	Address Object	Required. The address of the buyer who is returning the parcel. The fromAddress object requires the following fields: addressLines Either both cityTown and stateProvince, OR postalCode
toAddress	Address Object	Required. The merchant’s address. The API will replace this address with the closest PB Returns facility. The toAddress object requires the following fields: postalCode: This can be populated with any five numerical digits. For example: 00000 countryCode: Set to US
parcel	Parcel Object	Required. The parcel’s weight and dimensions. The parcel.weight object is required, but the object can contain any number for the weight value. The actual weight value is determined during handling and need not be accurate in this object.
rates	Array[Rates Object]	Required. Specifies the carrier, service, and parcel type. The array takes one rates object. The object requires the following fields and values: carrier: Set to PBCS serviceId: Set to PRCLSEL parcelType: Set to PKG
documents	Array[Documents Object]	Required. Defines the shipping label or QR code. Set the following, depending on whether you are printing a shipping label or QR code: Shipping label: type: Set to SHIPPING_LABEL size, fileFormat, and contentType: See Label Options below. customerData: Optional. To optionally add a custom barcode, enter the custom barcode parameters. To optionally add a custom function, add the function’s parameters, as set up with the PB implementation manager. QR Code: type: Set to QR_CODE fileFormat: Set to: GIF contentType: Set to either BASE64 or URL
shipmentOptions	Array[Object]	Required. Each object in this array defines a shipment option. Each object has the following two fields: name: String. The shipment option. value: String. The option’s value. The following shipment options are required: SHIPPER_ID: The merchant’s Shipper ID. If testing in Sandbox, and if you have not yet onboarded a merchant, use the default Shipper ID that comes with your developer account. CLIENT_ID: The merchant’s unique PB Returns client ID assigned when the merchant onboarded with PB Returns. If testing in Sandbox, set to NGST RETURN_ID: A merchant-generated identifier for the label. The Order ID is frequently used as this value. The identifier is included as part of the Pitney Bowes barcode. This value can be alpha-numeric, up to 20 characters in length. If testing in Sandbox, set to 123456789a CLIENT_SERVICE_FLAG: Set to Standard DISPOSITION_RULESET_ID: The ruleset (sort code) assigned to the merchant during onboarding.

Label Options

size	fileFormat	contentType	resolution
DOC_4X6	PDF PNG ZPL2	URL BASE64 BASE64	DPI_300 DPI_203, DPI_300 (default) DPI_203, DPI_300 (default)
DOC_6X4	PDF PNG ZPL2	URL BASE64 BASE64	DPI_300 DPI_203, DPI_300 (default) DPI_203, DPI_300 (default)
DOC_8X11	PDF	URL	DPI_300

Custom Barcode Parameters

To add an optional custom barcode at the bottom of the label, include the following parameters in the documents.customerData.labelDetails array.

Parameter	Value
barcodeValue	Set this to the information to be encoded in the barcode.
barcodeType	Set this to CODE128 to indicated the barcode uses the 128 barcode symbology.
barcodeHumanReadable	Set this to any human-readable information that is to accompany the barcode on the label.

For example:

"documents": [ {
    "customerData": {
        "labelDetails": [ {
            "name": "barcodeValue",
            "value": "10202"
        },{
            "name": "barcodeType",
            "value": "CODE128"
        },{
            "name": "barcodeHumanReadable",
            "value": "Order: 10202"
        } ]
    }
} ]

Response Elements

Name	Data Type	Description
shipmentType	String	Indicates the shipment is a return. This is set to: RETURN
fromAddress	Address Object	Address of the buyer who is returning the parcel.
toAddress	Address Object	The PB Returns facility.
parcel	Parcel Object	The parcel’s weight and dimensions.
rates	Array[Rates Object]	The carrier, service, parcel type, and service charges.
documents	Array[Documents Object]	Defines the shipping label or QR code. The type field indicates which is returned: SHIPPING_LABEL QR_CODE
shipmentOptions	Array[Object]	Each object in the array defines a shipment option.
shipmentId	String	The unique identifier for the shipment generated by the system.
parcelTrackingNumber	String	The tracking number assigned to the shipment.

Sample Requests

See the following examples:

• Create PB Returns Label

• Create a PB Returns Label QR Code

Create PB Returns Label

The following request creates a PB Returns label. For a sample label, click here.

Request to Create a PB Returns Label

curl -X POST ".../v1/shipments" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "Accept-Language: en-US" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "shipmentType": "RETURN",
    "fromAddress": {
        "company": "Shop",
        "name": "Kathryn Smith",
        "phone": "334-555-0000",
        "email": "kathryn@example.com",
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "toAddress": {
        "postalCode": "00000",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 0
        }
    },
    "rates": [ {
        "carrier": "PBCS",
        "serviceId": "PRCLSEL",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "contentType": "URL",
        "fileFormat": "PDF",
        "resolution": "DPI_300",
        "customerData": {
            "labelDetails": [ {
                "name": "<custom_value>",
                "value": "<custom_value>"
            } ]
        },
        "printDialogOption" : "NO_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    },{
        "name": "RETURN_ID",
        "value": "123456789a"
    },{
        "name": "CLIENT_SERVICE_FLAG",
        "value": "Standard"
    },{
        "name": "DISPOSITION_RULESET_ID",
        "value": "1"
     } ]
}'

Response for a PB Returns Label

{
    "fromAddress": {
        "company": "Shop",
        "name": "Kathryn Smith",
        "phone": "334-555-0000",
        "email": "kathryn@example.com",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830-6433",
        "countryCode": "US",
        "deliveryPoint": "52"
    },
    "toAddress": {
        "name": "PITNEY BOWES RETURNS",
        "addressLines": [
            "PARCEL RETURN SERVICE",
            "",
            ""
        ],
        "postalCode": "56901"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 0.0
        }
    },
    "rates": [ {
        "carrier": "PBCS",
        "parcelType": "PKG",
        "specialServices": [],
        "serviceId": "PRCLSEL"
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../f42be533cef48c09f76c1908c78a074.pdf",
        "customerData": {
            "labelDetails": [ {
                "name": "<custom_value>",
                "value": "<custom_value>"
            } ],
        },
        "fileFormat": "PDF",
        "size": "DOC_4X6",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    },{
        "name": "RETURN_ID",
        "value": "123456789a"
    },{
        "name": "CLIENT_SERVICE_FLAG",
        "value": "Standard"
    },{
         "name": "DISPOSITION_RULESET_ID",
         "value": "1"
    },{
        "name": "SMART_LABEL_BARCODE",
        "value": "7225108105012404020000000195465722I"
    } ],
    "parcelTrackingNumber": "9202390100763900000012487",
    "shipmentId": "NGST220023889032700"
}

Create a PB Returns Label QR Code

The following request creates a QR code that can be used to print a PB Returns label. For a sample QR code, click here.

Request to Create a PB Returns Label QR Code

curl -X POST ".../v1/shipments" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "Accept-Language: en-US" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "shipmentType": "RETURN",
    "fromAddress": {
        "company": "Shop",
        "name": "Kathryn Smith",
        "phone": "334-555-0000",
        "email": "kathryn@example.com",
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "toAddress": {
        "postalCode": "00000",
        "countryCode": "US"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 0
        }
    },
    "rates": [ {
        "carrier": "PBCS",
        "serviceId": "PRCLSEL",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "QR_CODE",
        "fileFormat": "GIF",
        "contentType": "BASE64"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    },{
        "name": "RETURN_ID",
        "value": "123456789a"
    },{
        "name": "CLIENT_SERVICE_FLAG",
        "value": "Standard"
    },{
        "name": "DISPOSITION_RULESET_ID",
        "value": "1"
     } ]
}'

Response for a PB Returns Label QR Code

{
    "fromAddress": {
        "company": "Shop",
        "name": "Kathryn Smith",
        "phone": "334-555-0000",
        "email": "kathryn@example.com",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830-6433",
        "countryCode": "US",
        "deliveryPoint": "52"
    },
    "toAddress": {
        "name": "PITNEY BOWES RETURNS",
        "addressLines": [
            "PARCEL RETURN SERVICE",
            "",
            ""
        ],
        "postalCode": "56901"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 0.0
        }
    },
    "rates": [ {
        "carrier": "PBCS",
        "parcelType": "PKG",
        "specialServices": [],
        "serviceId": "PRCLSEL"
    } ],
    "documents": [ {
        "contentType": "BASE64",
        "contents": "R0lGODlhWAJYAvAAAAAAAP///ywAAAAAWAJYAkAC/4yPqcvtD6OctNq...",
        "fileFormat": "GIF",
        "type": "QR_CODE"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    },{
        "name": "RETURN_ID",
        "value": "123456789a"
    },{
        "name": "CLIENT_SERVICE_FLAG",
        "value": "Standard"
    },{
         "name": "DISPOSITION_RULESET_ID",
         "value": "1"
    },{
        "name": "SMART_LABEL_BARCODE",
        "value": "7281006105012404002030000019584657I"
    },{
        "name": "LABEL_ID",
        "value": "93R64M6C"
    } ],
    "parcelTrackingNumber": "9204490188763900000012107",
    "shipmentId": "NGST220023818484327"
}

PB Returns Label

QR Code

A QR code is a two-dimensional barcode a buyer can use to print a PB Returns label at a Post Office or other label-printing facility. The buyer either scans the QR code or enters the QR code label ID. To provide a buyer with a list of nearby facilities that print labels from QR codes, use the Carrier Facility API. A buyer who has a printer can print a label by entering the QR code’s Label ID at the USPS Label Broker™ site: Label Broker

The following is a sample QR code:

Error Codes

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

 
 
 
 

• next
• previous |

© Copyright 2024 Pitney Bowes Inc. All rights reserved.