When Digital River acts as your fulfillment coordinator, you can use the Fulfillment Returns API to request and retrieve returns.

After you create a fulfillment return, you should monitor and respond to the events it emits.

Requesting a fulfillment return

When requesting a fulfillment return, you should first ensure the items you want to return are in the correct state. Once you've done that, you can then define and submit the return request.

Ensuring the correct item state

Before providing customers the option to return items, you should ensure that the items are in a shipped state. In other words, customers shouldn't be allowed to return pending, backordered, or cancelled items.

Defining and submitting a fulfillment return

When customers indicate they want to return all or part of a fulfillment order, submit a POST/fulfillment-returns request that specifies the items to return and in what quantity. More specifically, you need to provide us the identifier of the fulfillment order these items are attached to and data on the inventory items themselves.

For tracking purposes and to maintain data consistency, we also recommend you use the identifier of the upstream order as the upstreamId.

Fulfillment order identifier

The fulfillmentOrderId parameter is used to specify the identifier of the upstream fulfillment order associated with this return.

Inventory item data

For each item you want to return, you must provide the identifier it was assigned in the upstream fulfillment order and the quantity of that item to return.

Upstream data sent in a POST fulfillment return request

When setting certain parameters in a POST/fulfillment-returns request, you can retrieve their values from the following upstream Order and Fulfillment Order resources.

A fulfillment return

Once you've successfully submitted a POST/fulfillment-returns request, you get back a fulfillment return with a unique id which you can use to later retrieve the fulfillment return.

The object provides you information on each requested and accepted return item. A fulfillment return also contains enumerations that indicate its state and who initiated it.

Once the fulfiller approves the return, we also provide the return address where the customer should ship the items.

Returned items

The items array of a fulfilment return contains information on the requested and accepted returns. For each item in this array, we return the quantity you specified in the original return request as well as the quantityAccepted by the fulfiller.

When the quantityAccepted is less than the quantity, not all the products are approved for return.

We also indicate where the item is in its return lifecycle.

The fulfillment return life cycle

A fulfillment return has a defined lifecycle at both the order level and line item level. Each stage of that lifecycle is represented by the state attribute.

Order level

The state attribute at the order level indicates where a fulfillment return is in its lifecycle. The values for a successful fulfillment return (i.e., the happy path) are created > pending > accepted.

Line item level

The state attribute of a line item indicates where the object is in its fulfillment lifecycle. The values for a successfully returned line item (i.e., the happy path) are pending > accepted.

Return initiator

The type attribute indicates who initiated the return. A client return is standard and is typically initiated by a customer though the storefront. A warehouse return is initiated when a shipment is refused.

Return address

Once the return is approved by the fulfiller, we populate the location hash table. This data structure provides the address where the customer should return the products. To be notified of these approvals, you can subscribe to fulfillment_return.pending events.

Monitoring and responding to fulfillment returns

Once you have successfully submitted a POST/fulfillment-returns request, you can determine its status by either calling the API directly or listening for webhook events.

Retrieving a fulfillment return

There are two methods in the Fulfillment Returns API that can be used to retrieve fulfillment returns. You can either get a list of fulfillment returns filtered by optional query parameters. Or you can get an individual fulfillment return by sending its unique identifier as a path parameter.

Listening for fulfillment return events

You can configure your webhooks to listen for fulfillment return events. The data.object of every one of these events consists of a fulfillment return.

Return created events

When you submit a successful POST/fulfillment-returns request, we send you a fulfillment_return.created event. This indicates that your return request has been created by Digital River but not yet approved or rejected by the fulfiller.

Return approved events

If the fulfiller approves the return request, we send you a fulfillment_return.pending event. You can use this event to determine what items can be returned and where they can be sent.

Return accepted events

When the fulfiller notifies us that they've received and accepted the returned products, we send you a fulfillment_return.accepted event. If you don't want to reimburse customers until they have returned products, your integration should wait to receive this event before issuing refunds.

Return rejected events

A fulfillment_return.rejected event indicates the fulfiller has rejected the return.