Issuing refunds
Learn how to use the Refunds API to issue full and partial refunds
Last updated
Learn how to use the Refunds API to issue full and partial refunds
Last updated
The allows you to reimburse customers for product costs, shipping expenses, taxes, duties, and regulatory fees.
Once you , your integration should be set up to .
To tailor a refund so that customers are only reimbursed for specific, non-product related expenses, you must specify .
Before submitting a request, make sure you have:
The should only be used once an is partially or completely fulfilled.
This is because can only be created on with in a state of complete. To be notified of this state change event, you can subscribe to .
Once a is complete, Digital River increases .
At a high level, Digital River calculates these values by using the following formula:
At the order level, availableToRefundAmount reflects the unrefunded portion of an order's capturedAmount. This availableToRefundAmount may include product prices and any expenses related to shipping, duties, fees, and assessed taxes.
In the following example, note that each line item's availableToRefundAmount excludes its shipping.amount and shipping.taxAmount.
Omits type
Omits items[].type.
If you configure the request this way, Digital River will attempt to refund the specified quantity of items[] by the given percent or amount.
Along with product costs, line item-level refund requests using this configuration proportionally reimburse that items[].tax.amount. They do not, however, refund any shipping, regulatory fee, importer tax, or duty amounts (along with taxes assessed on those amounts) that are associated with that items[].
In these cases, if you retrieve an order's totalTax, and use that value to set amount in a POST /refunds, then a 400 Bad Request is returned.
In these cases, if you retrieve totalShipping, and use that value to set amount in a POST/refunds, then a 400 Bad Request is returned.
This state indicates that Digital River and the payment processor have all the information they need to initiate the refund process.
You can use refund.pending to trigger a notification to customers, informing them that their refund is being processed. Ensure you also update the refund status on their order details page.
In the payload, amount is how much you requested be refunded and refundedAmount is the actual reimbursed amount.
Some common reasons for a refund failure include:
A closed account
A frozen account due to suspected fraud
An expired credit card
Before submitting a , you can make a to determine whether the amount you're requesting is less than or equal to what's available.
A 200 OK response contains an availableToRefundAmount at both the and the .
The value of availableToRefundAmount reflects both and refunds.
availableToRefundAmount = charge(s)amount captured − ( amount + amount)
If you submit a POST/refunds whose amount is greater than the , or whose items[].amount is greater than that , then a 400 Bad Request is thrown:
In , items[].availableToRefundAmount reflects the unrefunded portion of that line item's amount plus its tax.amount. It doesn't include expenses related to shipping, duties, or fees.
If you'd like to refund shipping costs associated with an individual items[], then you can determine what customers paid by accessing items[].shipping.amount and items[].shipping.taxAmount.
A requires currency. After you submit this request, Digital River doesn't perform a currency conversion. As a result, the value you pass must be the same as the associated currency. If they're different, a 400 Bad Request is thrown:
Before submitting a request, must exist. Once satisfied, you can request a variety of refunds. The following sections provide information on how to reimburse:
You can issue product refunds at the and the .
If you'd like to refund an product costs, then ensure that the body of your :
Either (1) sets percent to a value in the range of 0.01 to 100.00 inclusive or (2) sets amount to a value that's less than or equal to the
If you set percent to 100 or amount to the , then Digital River attempts to reimburse the full availableToRefundAmount.
If you pass any lower percent or amount, then an product costs, shipping expenses, duties, and taxes are proportionally refunded.
Product refund requests do not reimburse . To do that, you must set to fees in a separate .
If you'd like to refund an items[] product costs, then ensure that the body of your :
Specifies an items[].quantity that is less than or equal to the corresponding items[].quantity in the .
Either (1) sets items[].percent to a value in the range of 0.01 to 100.00, inclusive or (2) sets items[].amount to a value that's less than or equal to that .
To get those expenses back, you could submit a separate POST /refunds that specifies .
If you want to only reimburse specific, non-product related costs, such as shipping, duties, , and taxes, your must specify type at either the order-level or the line item-level.
When , make sure you omit type in your POST /refunds request.
When type is shipping, fees, or duty, any taxes assessed on those particular components of the are also refunded.
For details on how to configure a refund request when type is tax or importer_tax, refer to .
In POST/refunds, by setting to tax, you can reimburse just the tax component of an order. You can't, however, partially refund taxes using type.
The doesn't support tax-only reimbursements at the items[] level.
If you submit a that specifies a type of tax, then either (1) percent must be 100 or (2) amount must be equal to the unrefunded portion of an totalTax. If either of these conditions are not met, then a 400 Bad Request is returned.
When refunding taxes, we recommend you use percent instead of amount. This is because an totalTax doesn't always reflect how much refundable tax exists. Previous refunds may have reduced what's available.
After you successfully submit a POST /refunds with a type of tax, Digital River attempts to reclaim the unrefunded portion of an totalTax.
You also can issue refunds only on shipping costs. To do this, set to shipping and specify an amount or percent.
We recommend using percent instead of amount. This is because an totalShipping doesn't always reflect the actual refundable shipping costs. Previous refunds may have reduced what's available.
Depending on the value you assign percent, passing a type of shipping fully or partially refunds both an shippingChoice.amount and shippingChoice.tax
After submitting a refund request, we recommend that your integration be set up to listen for the following :
When a is successful, Digital River sets the state to pending and creates a refund.pending event.
A 201 Created response code doesn't signify that the bank approved the refund. It only means that your refund request was successfully sent. To be notified of approved refunds, listen for the event.
In that have a state of pending , refundedAmount is always 0.0.
In some cases, customers must first supply their banking details before payment processors act on a refund request. This is common when the purchase was made with a or other .
When the bank requests this additional information, Digital River moves the state to pending_information and creates a refund.pending_information event.
For more information on how to handle this state change, refer to the page.
When a is successfully processed, Digital River moves its state to succeeded and creates an with a of refund.complete.
To , you can also to listen for .
You can use refund.complete to trigger a . The message (typically an email) should notify them that their refund request was successful and inform them how much they were reimbursed. Ensure you also update the refund status on their order details page.
If your refund request fails, Digital River moves the state to failed and creates a refund.failed event. In these cases, refundedAmount is 0.0.
For information on how to test refund failures, refer to .
If a refund fails, your integration can attempt to submit another using the same itemId(s) and/or orderId. Alternatively, you can try to .
An refundedAmount contains the total amount of all refunds issued on an order. This is a useful value to display to customers on their order details page.