Find Fulfillment Return Orders¶

HTTP Request¶

POST /v1/returns/search

Summary¶

This operation finds return orders, for returns to the fulfillment center.

Request URLs¶

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

Query Parameters¶

Query parameters are optional.

Name

Description

page

The page number to return in the result set. Page numbering starts at 1.

Default value: 1

size

The number of results per page.

Default value: 20

Request Headers¶

Name

Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

X-PB-TransactionId

Required. A unique identifier for the request, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Important: Ensure this is a unique ID.

Request Elements¶

Required fields are marked Required. All other fields are optional.

Name

Data Type

Description

clientId

String

Required. The client identifier assigned by Pitney Bowes.

sort

Array[String]

The property upon which to sort and the sort order. Use the following syntax:

<property>-<sort_direction>

Where <property> is one of the following:

createDate
updateDate
pbCreateDate
pbUpdateDate

And <sort_direction> is either of the following:

asc: ascending
desc: descending

For example: "pbCreateDate-asc"

searchFields

Array[Object]

The search criteria. Each object in the array is a name-value pair with the following two elements:

name: The name of the field upon which to search, entered as a String.

values: The values upon which to search. The array takes the data type of the field being searched.

The name field can take the following:

returnOrders
orders
sku
returnType
createDate
updateDate
pbCreateDate
pbUpdateDate

If included, the fields below are grouped with an AND clause to search against address of the customer:

customerFirstName
customerLastName
customerAddress1
customerAddress2
customerCity
customerStateOrProvince
customerPostalCode
customerCountry

Response Elements¶

Name	Data Type	Description
totalPages	Number	The number of pages in the result set.
totalElements	Number	The number of fulfillment return orders in the result set.
first	Boolean	If true, this is the first page of the result set.
last	Boolean	If true, this is the last page of the result set.
size	Number	The number of fulfillment return orders per page in the result set.
page	Number	The page number to return. Page numbering starts at 1.
sort	Array[String]	The sort order.
returnOrders	Array[Returns Object]	The fulfillment return orders. Each object in the array is a separate return order.

Returns Object in a Fulfillment Returns Order¶

The returnOrders array contains the Returns object:

Name	Data Type	Description
clientId	String	The client ID assigned by Pitney Bowes.
brand	String	The manufacturer’s brand name for the item. Maximum length: 30 characters
orderId	String	The Pitney Bowes ID for the original order.
returnClientOrderId	String	The client ID for the fulfillment return order. Maximum length: 50 characters
originalClientOrderId	String	The client ID for the original order.
returnOrderId	String	The Pitney Bowes ID for the fulfillment return order.
rmaNumber	String	The client’s RMA number for the return. The RMA number (Return Merchandise Authorization number) is used as a tracking number for parcel being returned to the fulfillment center. Maximum length: 35 characters
references	Array[Object]	Additional reference information for the order. Each object in the array is a name-value pair that defines a reference field and value.
references.name	String	The name of the reference field, up to 50 characters.
references.values	String	The value, up to 255 characters
createDate	String	The date and time the fulfillment return order was created in the client system, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
updateDate	String	The date and time the fulfillment return order was updated in the client system, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
pbCreateDate	String	The date and time Pitney Bowes receives information about the fulfillment return order, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
pbUpdateDate	String	The date and time Pitney Bowes receives updated information about the fulfillment return order, specified in the ISO 8601 format: `YYYY-MM-DDThh:mm:ssZ`
node	String	The Pitney Bowes Fulfillment Center where the return is expected to be processed.
fromAddress	Address Object	The address of the consumer who is sending back the package.
shippingDetails	Shipping Details Object	The carrier details for the fulfillment return order.
returnOrderCurrency	String	The default currency for the item-level costs.
returnOrderLines	Array[Return Order Lines Object]	The items included in the return order. Each item is a different object in the array.
returnReason	Array[String]	The reasons for the return order.

Sample Request¶

curl -X POST ".../v1/returns/search" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "1234",
    "sort": [
        "pbCreateDate-desc"
    ],
    "searchFields": [ {
        "name": "rmaNumber",
        "values": [
            "RMA12345678",
            "RMA23456789",
            ...
        ]
    } ]
}'

Sample Response¶

{
    "totalPages": "2,",
    "totalElements": "22,",
    "first": "true,",
    "last": "false,",
    "size": "20,",
    "page": "1,",
    "returns": [ {
        "clientId": "1234",
        "orderId": "ORA008917277321112334US",
        "returnClientOrderId": "ORRET851qwa1r",
        "originalClientOrderId": "ORCLIENT851qwa1r",
        "returnOrderId": "RO1234A7891178032111US",
        "rmaNumber": "RMA23456789",
        "createDate": "2022-03-23T15:48:44Z",
        "pbCreateDate": "2022-03-23T22:47:44Z",
        "node": "160",
        "fromAddress": {
            "name": "Mary Jones",
            "company": "Shop",
            "phone": "620-555-0000",
            "email": "mary@example.com",
            "addressLines": [
                "284 W Fulton St"
            ],
            "cityTown": "Garden City",
            "stateProvince": "KS",
            "postalCode": "67846",
            "countryCode": "US"
        },
        "shippingDetails": {
            "carrier": "UPS",
            "serviceId": "GROUND",
            "serviceName": "UPS Ground",
            "trackingNumber": "UPS11zxa10883211"
        },
        "returnOrderCurrency": "USD",
        "returnOrderLines": [ {
            "orderLineId": 1,
            "itemDetail": {
                "sku": "PRODUCT-SKU-987",
                "unitPrice": 100,
                "description": "Winter jacket"
            },
            "lineTotal": 100,
            "returnReason": [
                "WRONG SIZE"
            ],
            "quantity": 1
        } ],
        "notes": [
            "Reason 1"
        ],
        "returnReason": [
            "reason code"
        ]
    },
    ...
    ]
}

Error Codes¶

For lists of error codes returned by the Fulfillment APIs, please see 80-Prefix Error Codes (Fulfillment APIs).