Create Bulk Return Orders for Fulfillment

HTTP Request

POST /v1/returns/bulk

Summary

This operation creates and updates multiple fulfillment return orders. Each return is independently processed.

Request URLs

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

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

Name	Data Type	Description
returns	Array[Returns Object]	The return orders. Each object in the array is a separate fulfillment return order.

Returns Object in the Request

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

Name	Data Type	Description
operation	String	Specifies whether this Returns Object creates or updates a return order. If this field is not specified, the system will search for the order and, if it is found, update the order. If the order is not found, the system will create the order. This field takes one of the following values: CREATE UPDATE
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.
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
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.

Response Elements

Name	Data Type	Description
returns	Array[Returns Object]	The return orders. Each object in the array is a separate fulfillment return order.

Returns Object in the Response

Name	Data Type	Description
clientId	String	The client ID assigned by Pitney Bowes.
brand	String	The manufacturer’s brand name for the item, up to 30 characters.
orderId	String	The Pitney Bowes ID for the original order.
returnClientOrderId	String	The client ID for the fulfillment return order, up to 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, up to 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/bulk" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "returns": [ {
        "operation": "CREATE",
        "clientId": "1234",
        "orderId": "ORA008917277321112334US",
        "returnClientOrderId": "ORRET851qwa1r",
        "originalClientOrderId": "ORCLIENT851qwa1r",
        "rmaNumber": "RMAzxjj1a1331dsa",
        "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"
        ]
    },{
        "operation": "UPDATE",
        "clientId": "1234",
        "orderId": "ORDAA1267912211CO",
        "returnClientOrderId": "ORCLIENT8976r4w",
        "originalClientOrderId": "ORCLIENT8976r4w",
        "returnOrderId": "RO1234A7891178032111US",
        "rmaNumber": "RMAzxjj1128811azz",
        "node": "160",
        "fromAddress": {
            "name": "John Smith",
            "company": "ABC",
            "phone": "334-555-0000",
            "email": "john@example.com",
            "addressLines": [
                "2352 Bent Creek Rd"
            ],
            "cityTown": "Auburn",
            "stateProvince": "AL",
            "postalCode": 36830,
            "countryCode": "US"
        },
        "shippingDetails": {
            "carrier": "FedEx",
            "serviceId": "STANDARD",
            "serviceName": "<String>",
            "trackingNumber": "FX123909771101"
        },
        "returnOrderCurrency": "USD",
        "returnOrderLines": [ {
            "orderLineId": 1,
            "itemDetail": {
                "sku": "PRODUCT-SKU-111",
                "unitPrice": 50,
                "description": "Sport Relaxed Hoodie"
            },
            "lineTotal": 100,
            "returnReason": [
                "WRONG SIZE"
            ],
            "quantity": 2
        } ],
        "notes": [
            "Reason 1"
        ],
        "returnReason": [
            "reason code"
        ]
    },
    ...
    ]
}'

Sample Response

{
    "returns": [ {
        "clientId": "1234",
        "orderId": "ORA008917277321112334US",
        "returnClientOrderId": "ORRET851qwa1r",
        "originalClientOrderId": "ORCLIENT851qwa1r",
        "returnOrderId": "RO1234A7891178032111US",
        "rmaNumber": "RMAzxjj1a1331dsa",
        "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).

 
 
 
 

• next
• previous |

© Copyright 2024 Pitney Bowes Inc. All rights reserved.