Create a PB Standard Returns Label

HTTP Request

POST /v1/shipments

Summary

This operation creates a Pitney Bowes Standard 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 Standard 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 Standard Returns label, a merchant must first onboard with PB Standard. When a merchant onboards, the merchant is enrolled with a PB Standard facility and receives a set of PB Standard IDs.

Considerations

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

  2. PB Standard Returns are supported for domestic shipments only.

  3. PB Standard Returns use the Parcel Select Return mail class and the package parcel type.

  4. PB Standard Returns do not support special services.

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

  6. Available labels sizes are found on the Pitney Bowes page.

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

  8. 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 on this page.

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

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

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

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

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

  14. PB Standard 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 Standard 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 Standard Returns labels, merchants should contact their Pitney Bowes implementation teams.

Request / Response Elements

Required fields are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

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 Standard 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

Note that the response returns a different toAddress than the one you send in the request. The response specifies PITNEY BOWES RETURNS in the toAddress.

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 response specifies the service charges. 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 Standard Returns Labels for the valid combinations of values.

  • 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 Standard client ID assigned when the merchant onboarded with PB Standard.

    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.

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.

Custom Barcode Parameters

To add an optional custom barcode at the bottom of the label, include the following parameters in the documents.customerData objects’s 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"
        } ]
    }
} ]

Sample Requests

See the following examples:

Create Standard Returns Label

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

Request to Create a Standard 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 Standard 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 Standard Returns Label QR Code

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

Request to Create a Standard 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 Standard 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 Standard Returns Label

Sample PB Standard Returns Label

QR Code

A QR code is a two-dimensional barcode a buyer can use to print a PB Standard 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.