Digital River coordinated returns
Learn how to manage returns when Digital River is your designated fulfillment coordinator
Last updated
Learn how to manage returns when Digital River is your designated fulfillment coordinator
Last updated
In Digital River coordinated fulfillments, you can use the to request and retrieve returns. After you create a fulfillment return, you should monitor and respond to the events it emits.
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 define and submit the return request.
Before providing customers the option to return an item, you should ensure that the item is in a shipped state. Customers shouldn't be allowed to return pending, backordered, or cancelled items. You can obtain this information by retrieving the upstream fulfillment order or listening for fulfillment order events.
You may decide you want to build your integration so that customers have the option to cancel pending and backordered items.
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, data on the inventory items to return, and the identifier of the upstream order.
The fulfillmentOrderId parameter is used to specify the identifier of the upstream fulfillment order associated with this return.
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.
In the request, you should also set upstreamId to the identifier of the upstream order. This allows you to retrieve this identifier from the payload of a fulfillment_return.accepted event and use it when issuing refunds.
POST fulfillment return requestFulfillment Orders
id
âž”
fulfillmentOrderId
Fulfillment Orders
items[].id
âž”
items[].fulfillmentOrderItemId
Orders
id
âž”
upstreamId
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 with 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.
The items array of a fulfillment return contains information on requested and accepted returns. For each item in this array, quantity is the number of items you requested to be returned. The quantityAccepted is how many items have been accepted for return by the fulfiller.
When quantityAccepted is less than quantity, then the fulfiller has not yet approved all products for return.
A Digital River coordinated physical return has a defined lifecycle at both the fulfillment return level and line item level. Each stage of these lifecycles is represented by the state attribute.
The state attribute at the fulfillment return 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.
has been received by the fulfiller but they haven't approved or rejected it yet
created
has been approved by the fulfiller but the returned items haven't been received at the warehouse yet
pending
has been accepted by the fulfiller because the returned items have been received at the warehouse
accepted
has been rejected by the fulfiller
rejected
The state attribute at the item level indicates where a line item is in its return lifecycle. The values for a successfully returned line item (i.e., the happy path) are pending > accepted.
identifier is sent in a successfulPOST/fulfillment-returns request but the product(s) is not yet approved for return by the fulfiller
pending
has been received by the fulfiller at the warehouse and the product(s) return is accepted
accepted
return request is rejected by the fulfiller
rejected
The type attribute indicates who initiated the return. A client return is standard and is typically initiated by a customer through the storefront. A warehouse return is initiated when a shipment is refused.
Once a return request is approved by the fulfiller, we populate the location hash table. This data structure provides the address where a customer should return the products. To be notified of these approvals, you can subscribe to fulfillment_return.pending events.
Once you submit a POST /fulfillment-returns request, you can determine its status by calling the API directly or listening for webhook 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.
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 has not yet been approved or rejected by the fulfiller.
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 and then convey this information to the customer.
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.
A fulfillment_return.rejected event indicates the fulfiller has rejected the return.
When defining a POST /fulfillment-returns request, you can retrieve the required data from the following upstream and Fulfillment Order resources.
There are two methods in the that can be used to retrieve fulfillment returns. You can filtered by optional query parameters. You can also by sending its unique identifier as a path parameter.