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:

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:

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

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

Sample 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:

Sample QR Code

Error Codes

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