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

  1. For PB Expedited reference information, see the Pitney Bowes page.

  2. Expedited Returns use USPS as the carrier.

  3. Expedited Returns support USPS domestic shipments.

  4. Expedited Returns do not support shipments to international destinations, APO/FPO, or US territories.

  5. There is no charge to print an Expedited Returns label. Postage is deducted only if an item is returned.

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

  7. Labels retrieved through URLs are available for 24 hours after label creation.

  8. Expedited Returns labels cannot be voided. Voiding an Expedited Returns label results in an error.

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

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

    FCM

    PKG

    PRCLSEL

    PKG

    PM

    One of the following: PKG, FRE, LGLFRENV, PFRENV

  • specialServices: Optional. Expedited Returns supports 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:

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

Sample Expedited Returns Label

Error Codes

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