Update a Fulfillment Return Order

HTTP Request

PUT /v1/returns/{returnOrderId}

Summary

This operation updates an order for a return to a fulfillment center. You must pass the whole return order object again to make the update. You cannot pass a partial object.

Request URLs

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

Path Parameter

Name

Description

returnOrderId


Required. The fulfillment return order ID assigned by Pitney Bowes.

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

Important

You must pass the whole return order object again to make the update. You cannot pass a partial object.

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.

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

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 PUT ".../v1/returns/{returnOrderId}" \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "1234",
    "orderId": "ORDAA1267912211CO",
    "returnClientOrderId": "ORCLIENT8976r4w",
    "originalClientOrderId": "ORCLIENT8976r4w",
    "rmaNumber": "RMAzxjj1128811azz",
    "node": "160",
    "fromAddress": {
        "name": "John Smith",
        "company": "ABC",
        "phone": "111-111-1111",
        "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 Colorblocked Relaxed Hoodie"
        },
        "lineTotal": 100,
        "returnReason": [
            "WRONG SIZE"
        ],
        "quantity": 2
    } ],
    "returnReason": [
        "reason code"
    ]
}'

Sample Response

{
    "clientId": "1234",
    "orderId": "ORDAA1267912211CO",
    "returnClientOrderId": "ORCLIENT8976r4w",
    "originalClientOrderId": "ORCLIENT8976r4w",
    "returnOrderId": "RO1234A7891178032111US",
    "rmaNumber": "RMAzxjj1128811azz",
    "createDate": "2022-03-23T15:48:44Z",
    "updateDate": "2022-03-25T10:48:44Z",
    "pbCreateDate": "2022-03-23T20:47:44.747Z",
    "pbUpdateteDate": "2022-03-25T21:47:44.747Z",
    "node": "160",
    "fromAddress": {
        "name": "John Smith",
        "company": "ABC",
        "phone": "111-111-1111",
        "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 Colorblocked Relaxed Hoodie"
        },
        "lineTotal": 100,
        "returnReason": [
            "WRONG SIZE"
        ],
        "quantity": 2
    } ],
    "returnReason": [
        "reason code"
    ]
}

Error Codes

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