Note

As of July 9, 2023: USPS has introduced the new parcel Ground Advantage Return service to replace FCM and PRCLSEL. For details, see this item in the Release Notes.

Create a PB Expedited Returns Label¶

HTTP Request¶

POST /v1/shipments

Summary¶

This operation prints a PB Expedited Returns label for use in a package return. The PB Expedited Returns service allows you to use discounted pricing when printing a return label. The label is a post-paid label and incurs no charges at the time of print. Postage for the label is deducted only if the label is used. Pricing is based on actual package properties captured by USPS^® Automated Package Verification equipment. The label is valid for 90 days after the time of print.

Discounted Pricing¶

To use discounted rates, specify the rate plan or NSA in the request header when issuing this API call.

Considerations¶

For an overview of PB Expedited services and operations, see the Pitney Bowes reference page.
PB Expedited Returns use USPS as the carrier.
PB Expedited Returns support USPS domestic shipments. Expedited Returns do not support shipments to APO/FPO or US territories.
There is no charge to print an Expedited Returns label. Postage is deducted only if an item is returned.
Pitney Bowes verifies addresses for accuracy against current USPS data and makes corrections to delivery lines and last lines when possible. You can optionally enable minimal address validation through the MINIMAL_ADDRESS_VALIDATION shipment option. For a comparison of complete and minimal address validation, see What is minimal address validation?

IMPORTANT: If you enable minimal address validation, the shipper takes 100% responsibility for any undelivered packages due to violation of carrier-addressing guidelines and is responsible for any surcharge or adjustment fee levied by the carrier for such a violation.
PB Expedited Returns support only one special service (specialServices), the Signature Confirmation (Sig) special service.
Labels retrieved through URLs are available for 24 hours after label creation.
Expedited Returns labels cannot be voided. Voiding an Expedited Returns label results in an error.
To view transaction history for Expedited Returns labels, use the Transaction Reports API. The status field in the response body displays Printed if the label is printed but has not been delivered. If the label has been delivered, the field displays Charged.
For answers to common questions, please see the Expedited Returns Label FAQs.

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 Generate an 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-Shipper-Rate-Plan	Shipper rate plan, if applicable. For more information, see this FAQ.
X-PB-Integrator-CarrierId	Negotiated services rate, if applicable.
X-PB-UnifiedErrorStructure	Recommended. Set this to `true` to use the standard error object if an error occurs.

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 this to RETURN.

fromAddress

Address Object

Required. The address of the user who is returning the merchandise. The fromAddress object requires the following fields:

addressLines
cityTown
stateProvince
postalCode
countryCode
Either name or company
email
phone

toAddress

Address Object

Required. The address the merchandise is returned to. The following fields are required:

addressLines
postalCode
countryCode

parcel

Parcel Object

Required. The parcel’s weight and dimensions. Enter the dimensions in inches. Set dimension.unitOfMeasurement to IN.

rates

Array[Rates Object]

Required. Specifies the carrier, service, and parcel type. The response specifies the service charges. The array takes one rates object. Set the following:

carrier: Required. Set to USPS.

serviceId and parcelType: Required. Set to one of these valid combinations. For definitions, see the Pitney Bowes reference page:

serviceId:	parcelType:
`UGA`	`PKG`
`PM`	One of the following: `PKG`, `FRE`, `LGLFRENV`, `PFRENV`
`FCM-Letter`	Letters are not affected by this change.
`FCM-PKG, PRCLSEL, and STDPOST`	These are all deprecated services.

specialServices: Optional. Expedited Returns support one special service, the Sig (Signature Confirmation) special service. Sig does not take input parameters.

documents

Array[Documents Object]

Required. Defines the label. Set the following:

type: Set to SHIPPING_LABEL.
printDialogOption: Set as described here on the Resource Objects page.
size, fileFormat, and contentType: Set to one of the following valid combinations. Note that the size value uses an uppercase X.

size

fileFormat

contentType

DOC_4X6

PDF
PNG
ZPL2

URL
BASE64
BASE64

DOC_8X11

PDF
PNG

URL
BASE64

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 SHIPPER_ID shipment option is required and must be set to the merchant’s Shipper ID. For all available options, see Shipment Options.

shipmentId

String

RESPONSE ONLY. A unique identifier for the shipment.

parcelTrackingNumber

String

RESPONSE ONLY. The tracking number for the shipment.

Sample Request¶

curl -X POST ".../v1/shipments" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "shipmentType": "RETURN",
    "fromAddress": {
        "addressLines": [ "27 Waterview Drive" ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "name": "John Smith",
        "phone": "203-555-0000",
        "email": "john@example.com",
        "residential": false
    },
    "toAddress": {
        "addressLines": [ "284 W Fulton" ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846",
        "countryCode": "US",
        "company": "Shop",
        "name": "Mary Jones",
        "phone": "620-555-0000",
        "email": "mary@example.com",
        "residential": false
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 1
        },
        "dimension": {
            "unitOfMeasurement": "IN",
            "length": 6,
            "width": 0.25,
            "height": 4,
            "irregularParcelGirth": 0.002
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "serviceId": "PM",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "size": "DOC_4X6",
        "contentType": "URL",
        "fileFormat": "PDF",
        "type": "SHIPPING_LABEL",
        "printDialogOption": "NO_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'

Sample Response¶

{
    "fromAddress": {
        "addressLines": [
            "27 Waterview Dr"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484-4301",
        "countryCode": "US",
        "carrierRoute": "C010",
        "deliveryPoint": "27",
        "company": "",
        "name": "John Smith",
        "phone": "203-555-0000",
        "email": "john@example.com",
        "residential": false
    },
    "toAddress": {
        "addressLines": [
            "284 W Fulton"
        ],
        "cityTown": "Garden City",
        "stateProvince": "KS",
        "postalCode": "67846",
        "countryCode": "US",
        "company": "Shop",
        "name": "Mary Jones",
        "phone": "620-555-0000",
        "email": "mary@example.com",
        "residential": false,
        "carrierRoute": "C007",
        "deliveryPoint": "84"
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "OZ",
            "weight": 1
        },
        "dimension": {
            "length": 6,
            "width": 0.25,
            "height": 4,
            "unitOfMeasurement": "IN",
            "irregularParcelGirth": 0.002
        }
    },
    "rates": [ {
        "carrier": "USPS",
        "parcelType": "PKG",
        "inductionPostalCode": "06484",
        "specialServices": [ {
            "fee": 0,
            "specialServiceId": "USPS Returns Service"
        } ],
        "dimensionalWeight": {
            "unitOfMeasurement": "OZ",
            "weight": 0
        },
        "serviceId": "PM",
        "baseCharge": 6.95,
        "currencyCode": "USD",
        "destinationZone": "1",
        "totalCarrierCharge": 6.95
    } ],
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../usps/984189112/inbound/label/60de5047fd12345f8a1868de0f6d0c4.pdf",
        "fileFormat": "PDF",
        "size": "DOC_4X6",
        "type": "SHIPPING_LABEL"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "parcelTrackingNumber": "9301920516000000240756",
    "shipmentId": "USPS2200184732846980"
}

Sample Expedited Returns Label¶

Error Codes¶

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