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. The label is valid for 90 days after the time of print.

Benefits of PB Expedited Returns¶

PB Expedited Returns provide the following benefits:

You can use discounted pricing when printing an Expedited Returns label. To use discounted rates, specify the rate plan or NSA in the request header when issuing this API call.
Pricing for Expedited Returns is based on actual package properties captured by USPS® Automated Package Verification equipment.

Things to Consider¶

Expedited Returns use USPS as the carrier.
Expedited Returns support USPS domestic shipments.
Expedited Returns do not support shipments to international destinations, APO/FPO, or US territories.
There is no charge to print an Expedited Returns label. Postage is deducted only if an item is returned.
The following USPS services and parcel types are supported with Expedited Returns:

Service Name Service ID Parcel Type

First-Class Package Return Service FCM PKG

Priority Mail Return Service PM PKG, FRE, LGENV, LGLFRENV, PFRENV

Ground Return Service PRCLSEL PKG
The following USPS special services are supported. For important considerations, please see USPS special services.

Special Service Special Service ID

Signature Confirmation Sig
The following label sizes and file formats are supported. For important considerations, please see USPS Labels.

Size File Format

DOC_4X6 PDF, PNG, ZPL2

DOC_8X11 PDF, PNG

When issuing the API call, you must set the following:

Field	Value
`shipmentType`	`RETURN`
`toAddress`	The address the merchandise is returned to. The following fields are required: `addressLines` `postalCode` `countryCode`
`fromAddress`	The address of the user who is returning the merchandise. The following fields are required: `addressLines` `cityTown` `stateProvince` `postalCode` `countryCode` Either `name` or `company` `email` `phone`

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.
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.
Expedited Returns labels cannot be voided. Voiding an Expedited Returns label results in an error.
Labels retrieved through URLs are available for 24 hours after label creation.
For answers to common questions, please see the Expedited Returns Label FAQs.
PB Expedited Returns labels are not manifested.

Request URIs¶

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/shipments
Production: https://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. Important: You must ensure this is a unique id.
X-PB-Shipper-Rate-Plan	USPS Only. Shipper rate plan, if applicable. For more information, see this FAQ.
X-PB-Integrator-CarrierId	USPS Only. 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¶

The API call sends and receives a Shipment Object. The following table describes all possible fields in a Shipment Object.

Important

Some fields do not apply to this operation and are marked accordingly.

Name	Data Type	Description
fromAddress	Address Object	Required. Origin address. If you want a different address to appear on the label from the one listed here, see How do I print a return address that is different from the origin address?
toAddress	Address Object	Required. Destination address. FedEx, UPS: If you are shipping with FedEx or UPS to Puerto Rico or an international destination, and if the importer is different from the final recipient, this is the address of the importer. Enter the recipient’s address in the `soldToAddress` object. If importer’s address is the same as the final recipient, the `toAddress` and `soldToAddress` must match.
altReturnAddress	Address Object	USPS, CBDS Only. Applies as follows: USPS: If you are sending an international shipment through USPS and if you have set the NON_DELIVERY_OPTION shipment option to `redirect`, then enter the address that a returned parcel should go to. CBDS: For a Create Shipment request, this is the address used to return a parcel from the CBDS Consolidation Center. If omitted, the `fromAddress` is used. The `altReturnAddress` is not returned in the response.
parcel	Parcel Object	Required. Contains physical characteristics of the parcel.
rates	Array[Rates Object]	Required. Specifies the carrier, service, parcel, and other information. In a response, this field also contains the service charges. Important: In a request, the `rates` array can contain only one rates object.
documents	Array[Documents Object]	Conditional. Defines the label, manifest, or other shipping document created by the API call. This field is required except in the following cases: This field does not apply to Rate Parcel requests. This field does not apply to the Create CBDS Shipment request if the merchant prints the first-label prior to invoking the API.
shipmentOptions	Array[Object]	Required. Each object in this array defines a shipment option. Specify each option as a name-value pair in the array. The `SHIPPER_ID` option is required. For any additional requirements for a carrier or service, please see the Things to Consider section on the carrier’s Create Shipment page.
name	String	The name of the shipment option.
value	String	The value of the shipment option.
customs	Object	Conditional. For shipments that use customs forms, this object contains the customs information. This field is required for the following carriers in the following situations: USPS: Required for shipments to international destinations or to APO/FPO/DPO, Territories/Possessions, or FAS. CBDS: Required for all shipments. FedEx: Required for shipments to international destinations and Puerto Rico. UPS: Required for shipments to international destinations and Puerto Rico.
customsInfo	Customs Info Object	Customs clearance information used to fill out a commercial invoice.
customsItems	Array[Customs Items Object]	Information about each commodity in the shipment, used for customs clearance. The maximum number of objects in this array is 30.
domesticShipmentDetails	Domestic Shipment Details Object	CBDS Only. Required if the merchant prints the first-mile label prior to invoking the Create CBDS Shipment API. This object contains information about the first-mile leg of the shipment.
soldToAddress	Address Object	FedEx, UPS Only. The final recipient of a the shipment. Required for a shipment from the U.S. to Puerto Rico or to an international destination. Otherwise optional. This address must match the `toAddress.countryCode`, with the exception of shipments to Canada and to U.S. satellite countries. If the final recipient’s address is the same as the importer’s address, the entries in the `soldToAddress` object must match the entries in the `toAddress` object.
shipmentType	String	Return Labels Only. Set this to `RETURN`. Required for Expedited Returns and Standard Returns.
references	Array[Object]	Merchant-defined values. Applies to the following: PB Standard: Optional. See References Array in PB Standard. CBDS: Conditional. See References Array in a CBDS Request.
shipmentId	String	RESPONSE ONLY. Unique identifier for the shipment, generated by the system in response to shipment purchase.
parcelTrackingNumber	String	RESPONSE ONLY. Tracking number assigned to the shipment by the system.

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-000-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-000-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 PB Complete Shipping APIs error codes, see Error Codes.

Service Name	Service ID	Parcel Type
First-Class Package Return Service	`FCM`	`PKG`
Priority Mail Return Service	`PM`	`PKG`, `FRE`, `LGENV`, `LGLFRENV`, `PFRENV`
Ground Return Service	`PRCLSEL`	`PKG`

Special Service	Special Service ID
Signature Confirmation	`Sig`

Size	File Format
`DOC_4X6`	`PDF`, `PNG`, `ZPL2`
`DOC_8X11`	`PDF`, `PNG`