Create a Returns Management Request¶

HTTP Request¶

POST /v1/returns

Summary¶

This operation saves a Return Order. The API should be processed after a PB Return label or PB Return QR Code is printed.

Considerations¶

This operation is performed after a PB Return Create Label transaction is run.
It is always one Return Management Request to each Return label or QR Code request.

Request URLs¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/returns
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/returns

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-IntegratorId	Required. This is your Developer ID.
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.

Request / Response Elements¶

Name	Data Type	Description
fromAddress	Address Object	Required. The origin address. The `fromAddress` object requires the following fields: `addressLines` `postalCode` `countryCode` `name`
shipperId	String	Required. Set this to the merchant’s Shipper ID.
clientId	String	Required. The PB client ID assigned to the merchant during onboarding. If testing on Sandbox, set this to NGST. (Note: This is optional for PB Delivery but required for PB Returns.)
rmaId	String	Required. The RETURN_ID field that was used when generating the Return label or QR code.
pbReturnsBarcode	String	Required. The PB_STANDARD_RETURNS_LABEL_BARCODE that was returned in the Response from the Return request.
orderId	String	Required. The order identifier.
orderDate	String	Required. The date the order was processed.
parcelTrackingNumber	String	Required. The `parcelTrackingNumber` that was returned in the Response from the Return request.
returnLineItems	Object The Return Line Item	Required. An object that contains and describes the items included in the return.
options	Array	Optional. An array of name/value pairs that describe the options of the return.

The Return Line-Item Object¶

If the shipment has multiple types of items, create separate customsItems objects for each. The array takes a maximum of 30 objects.

Name	Data Type	Description
orderItemId	String	Optional. An identifier for the individual order item.
returnReason	Object	Required. The reason the item was being returned.
returnReason.description	String	Required. The description of the return reason.
sku	String	Required. The SKU of the item returned.
options	String	Optional. The options of the item returned.

Response Elements¶

Name

Data Type

Description

returnId

String

The unique identifier for the shipment generated by the system.

Sample Request¶

curl --location 'https://api.pitneybowes.com/shippingservices/v1/returns' \
--header 'X-PB-TransactionId: RTNMGT_PAB421127' \
--header 'Authorization: Bearer <oauth_token>' \
--header 'Content-Type: application/json' \
--header 'X-PB-IntegratorId: 43609570' \
--header 'Accept-Language: en-US' \
--data '{
    "shipperId": "<Shipper ID>",
    "clientId": "NGST",
    "rmaId": "3040401",
    "pbReturnsBarcode": "35467",
    "orderId": "3040401",
    "orderDate": "2023-04-05T13:27:53.101Z",
    "parcelTrackingNumber": "92023927247699000000057849",
    "shipmentId": "NGST2200455427757391",
    "fromAddress": {
        "name": "Paul Wright",
        "phone": "203-555-1213",
        "addressLines": [
            "27 Waterview Drive",
            "Suite 234"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US"
    },
    "returnLineItems": [
        {
            "orderItemId": "9876",
            "returnReason": [
                {
                    "description": "rtn line item rtn reason desc"
                }
            ],
            "quantity": 1,
            "sku": "TestSku_1",
            "description": "rtn line item desc",
            "options": [
                {
                    "name": "mediaURL",
                    "value": "https://www.pitneybowes.com/etc/designs/pb-redesign/resources/images/favicon/favicon_72.png"
                },
                {
                    "name": "itemVerify",
                    "value": "true"
                }
            ]
        }
    ]
 }'

Sample Response¶

{
    "returnId": "124LC9MMSCK00"
}

Error Codes¶

Error codes specific to address validation are seven-digits long and start with 10. See the address-specific errors in 10-Prefix Error Codes.

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