If you're using a third-party reverse logistics service, you can use the Returns API to help manage the returns and refunds process.
Once a customer's request to return purchased products is approved, use this API to notify Digital River that you authorized a return and then, after the returned goods have been received, inspected, and signed off, move them into an accepted state.
Once all the authorized goods are accepted, Digital River creates one or more refund pending events that you can listen for with a configurable webhook.
If customers request a return, and you authorize their request, your order management system should define and create a return authorization in Digital River's system.
The request must contain the associated with the products that are being returned.
Items
For each items[], define itemId or skuId and the quantity of goods authorized for return.
Reason and location
You can optionally provide a return reason and location. Both of these are pass-through values but can be useful for tracking, customer notifications, and record-keeping purposes.
Creating a return authorization
To create a return authorization, send your secret API key and request payload in a POST /returns.
If items[].quantity exceeds the quantity that's eligible for return, you receive the following error:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "quantity_too_large",
"parameter": "items[0].qty",
"message": "Return quantity is larger than order quantity"
}
]
}
Return authorization
In items[], the quantityAccepted represents the number of products that have been received and accepted. In the 201 Created, it's always 0 but may increase, depending on the results of the return acceptance process.
If the full quantity of goods specified in the return authorization arrives in a single shipment, and you or your third-party reverse logistics service accepts their condition, send a POST /returns/{id} with state set to accepted in the body of the request:
Digital River handles your request by setting the state of the return and each of its items[] to accepted, and then creating two types of events, return.accepted and refund.pending.
If the refund is successfully processed, refund.complete is next created. If, for some reason, it's not, then you'll need to handle refund.failed.
If the goods in the return authorization don't arrive in a single shipment, you or your third-party reverse logistics service can accept each item separately.
For example, you might have created a return authorization that contains two items[].
For the first items[] in this example, the full, authorized quantity might arrive in an initial shipment that doesn't contain any products from the second items[].
If the remainder of products authorized for return arrive in a second shipment, then submit another update request that sets the quantity of that items[] to the appropriate value and it's state to accepted.
Once the request is successfully submitted, Digital River sets the state of the return and each of its items[] to created and generates an with a type of return.created.
Each items[] in the response contains a skuId , which you can use to make a request and access product data.
If customers follow your instructions on how to return their goods, and they arrive in the expected quantity and quality, you'll need to notify Digital River that the return is accepted so that we can issue a .
To handle this, in the body of an , set the quantity of the first items[] to the appropriate value and it's state to accepted.
A successful request moves the state to accepted and generates return.accepted as well as one or more refund.pending events, each containing unique .
are only created when a state moves to accepted. For this to occur, each items[].state in the resource must also be accepted. To make that happen, the authorized quantity of each items[] must be equal to its quantityAccepted.
In other words, the is designed to handle the scenario where the full quantity of goods in a return authorization is sent back and approved, and then the customer is issued a refund.
If you'd like to provide refunds on partial returns, then your application should use the . For details, refer to Issuing refunds.
