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
Ground Return Service PRCLSEL
PKG
Priority Mail Return Service PM
PKG
,FRE
,LGLFRENV
,PFRENV
The following USPS special service is supported. For important considerations, please see PB Expedited Special Services.
Special Service Special Service ID Signature Confirmation Sig
The following label sizes and file formats are supported. For important considerations, please see 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
orcompany
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 displaysPrinted
if the label is printed but has not been delivered. If the label has been delivered, the field displaysCharged
.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 | 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¶
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 |
altReturnAddress | Address Object | PB Expedited, CBDS Only. Applies as follows:
|
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 |
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:
|
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 |
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:
|
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 If the final recipient’s address is the same as the importer’s address, the
entries in the |
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:
|
hazmatDetails | Hazmat Details Object | PB Standard Only. If shipping hazardous materials with PB Standard, use this object. |
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.