Note
The Fulfillment APIs are coming soon.
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 Default value: |
size |
The number of results per page. Default value: |
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 ( Important: Ensure this is a unique ID. |
Request Elements¶
The POST operation sends an object with the fields described here. 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:
Where
And
For example: |
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. |
Response Elements¶
The response returns an object with the fields described here.
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 in the response contains the Returns object, described in the table below. (The table below describes the Returns object for all operations that use it. Some fields in the table are labeled Required, meaning they are required in operations that send this object in the payload.)
Name |
Data Type |
Description |
---|---|---|
clientId |
String |
Required. 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 |
RESPONSE ONLY. 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[References Object] |
Additional reference information for the order. Each object in the array is a name-value pair that defines a reference field and value. |
createDate |
String |
Reserved for future use. |
updateDate |
String |
Reserved for future use. |
pbCreateDate |
String |
RESPONSE ONLY. The date and time Pitney Bowes receives information about the fulfillment return order, specified in the ISO 8601 format: |
pbUpdateDate |
String |
RESPONSE ONLY. The date and time Pitney Bowes receives updated information about the fulfillment return order, specified in the ISO 8601 format: |
node |
String |
The Pitney Bowes Fulfillment Center where the return is expected to be processed. |
fromAddress |
The address of the consumer who is sending back the package. |
|
shippingDetails |
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. |
operation |
String |
Specifies whether to create or update a given return order in a Bulk Return Orders operation. This field applies only to Bulk Return Orders. If this field is not specified for a return order, the system will search for the order and, if it is found, the system will update the order. If the order is not found, the system will create the order. This field takes the following values:
|
Sample Request¶
curl -X POST ../v1/returns/search \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
"clientId": "NGST",
"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": "NGST",
"orderId": "ORA008917277321112334US",
"returnClientOrderId": "ORRET851qwa1r",
"originalClientOrderId": "ORCLIENT851qwa1r",
"returnOrderId": "RO1234A7891178032111US",
"rmaNumber": "RMA23456789",
"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).