Issuing refunds
Learn how to create full and partial refunds for orders.
You can create refund requests for an amount or for a percentage at both the order-level and item-level. The Refunds API also allows you to indicate whether you'd like the refund to apply to shipping, taxes, fees or duties.
You can also issue multiple partial refunds until the entire order charge has been refunded. You cannot however refund a total greater than the original charge amount and you should always check the available to refund amount before creating a Refund request.

Refund requests

The following section explains the different kinds of refund requests you can submit. They consist of refunding an amount or percent at either the order-level or item-level.
To issue a refund with the Refunds API, create a Refund by providing the order or invoice identifier associated with the charge, along with any other required parameters.
Refund order amount
Refund order percent
Refund item amount
Refund item percent

Refunding an amount at the order-level

Attribute
Description
orderId
The unique identifier of the order. You are required to provide this parameter or invoiceId.
invoiceId
The unique identifier of the invoice. You are required to provide this parameter or orderId.
currency
A three-letter alphabetic ISO currency code.
amount
The amount of the refund.
reason
A value that indicates the reason for the refund. Reason codes are arbitrary, searchable strings you may use to capture the reason for the refund.
metadata
Additional structured information for the object.

Example

The following create Refund request specifies an amount of the total order to be refunded. An error response will be returned if the amount specified in the request exceeds the available to refund amount.
1
curl --location --request POST 'https://api.digitalriver.com/refunds' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"orderId": "178483320336",
6
"currency": "USD",
7
"amount": 8.00,
8
"reason": "requested_by_customer"
9
}'
Copied!
A Refund object with a unique id is returned. The actual refundedAmount is 0.0 because the Refund remains in a state of pending. And since the refund was requested at the order-level, the items array is empty.
1
{
2
"id": "re_bd224430-53b0-4a45-854e-5205c795a75a",
3
"amount": 8.0,
4
"createdTime": "2020-06-26T21:56:08Z",
5
"currency": "USD",
6
"items": [],
7
"orderId": "178483320336",
8
"reason": "requested_by_customer",
9
"refundedAmount": 0.0,
10
"state": "pending",
11
"liveMode": false
12
}
Copied!

Refunding a percent at the order-level

Attribute
Description
orderId
The unique identifier of the order. You are required to provide this parameter or invoiceId.
invoiceId
The unique identifier of the invoice. You are required to provide this parameter or orderId.
currency
A three-letter alphabetic ISO currency code.
percent
The percent of the refund.
reason
A value that indicates the reason for the refund. Reason codes are arbitrary, searchable strings you may use to capture the reason for the refund.
metadata
Additional structured information for the object.

Example

The following create Refund request specifies a percent of the total order to be refunded. Percent values greater than 100 are not allowed.
1
curl --location --request POST 'https://api.digitalriver.com/refunds' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"orderId": "178483320336",
6
"currency": "USD",
7
"percent": 25,
8
"reason": "requested_by_customer"
9
}'
Copied!
A Refund object with a unique id is returned. The request specified a percent but the response returns an amount to refund. The actual refundedAmount is 0.0 because the Refund remains in a state of pending. And since the refund was requested at the order-level, the items array is empty.
1
{
2
"id": "re_d25e5e3c-55dc-414b-bbcc-84de2c16cd3b",
3
"amount": 1.86,
4
"createdTime": "2020-06-26T22:01:34Z",
5
"currency": "USD",
6
"items": [],
7
"orderId": "178483320336",
8
"reason": "requested_by_customer",
9
"refundedAmount": 0.0,
10
"state": "pending",
11
"liveMode": false
12
}
Copied!

Refunding an amount at the item-level

Parameter
Description
orderId
The unique identifier of the order. You are required to provide this parameter or invoiceId.
invoiceId
The unique identifier of the invoice. You are required to provide this parameter or orderId.
currency
A three-letter alphabetic ISO currency code.
items
An array of items that you want to refund. For each element, you are required to provide the itemId and the amountto refund value.
The optional quantity attribute represents how many items you'd like to apply the refund to. If you don't provide a value, we default to the quantity specified in the line item object.
We then multiply the amount and the quantity when determining the total refund.
The type represents the type of charge to refund. Refer to Specifying the type of refund for more information.
reason
A string value that indicates the reason for the refund. Reason codes are arbitrary, searchable strings you may use to capture the reason for the refund.
metadata
Additional structured information for the object.

Example

You can create an amount refund for each line item in an Order. For each item, the amount you specify is multiplied by the quantity. So the total refund request amount in the following example is 130.00 USD.
1
curl --location --request POST 'https://api.digitalriver.com/refunds' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"orderId": "178582150336",
6
"currency": "USD",
7
"items": [
8
{
9
"itemId": "97817170336",
10
"amount": 20.0,
11
"quantity": 2
12
},
13
{
14
"itemId": "97817180336",
15
"amount": 30.0,
16
"quantity": 3
17
}
18
],
19
"reason": "requested_by_customer"
20
}'
Copied!
A Refund object with a unique id is returned. At both the order-level and item-level, the actual refundedAmount is 0.0 because the Refund remains in a state of pending.
1
{
2
"id": "re_e34afffc-175f-4e50-b79f-4b68484d004b",
3
"createdTime": "2020-06-26T22:24:08Z",
4
"currency": "USD",
5
"items": [
6
{
7
"amount": 40.0,
8
"quantity": 2,
9
"refundedAmount": 0.0,
10
"skuId": "63472e51-4fd7-4865-a7c9-b2cfd103713d",
11
"itemId": "97817170336"
12
},
13
{
14
"amount": 90.0,
15
"quantity": 3,
16
"refundedAmount": 0.0,
17
"skuId": "bc8ee185-1d33-415c-b257-ee8f69ae3838",
18
"itemId": "97817180336"
19
}
20
],
21
"orderId": "178582150336",
22
"reason": "requested_by_customer",
23
"refundedAmount": 0.0,
24
"state": "pending",
25
"liveMode": false
26
}
Copied!

Refunding a percent at the item-level

Parameter
Description
orderId
The unique identifier of the order. You are required to provide this parameter or invoiceId.
invoiceId
The unique identifier of the invoice. You are required to provide this parameter or orderId.
currency
A three-letter alphabetic ISO currency code.
items
An array of items that you want to refund. For each element, you are required to provide the itemId and the percentto refund value.
You're also required to specify the quantity attribute, which represents how many items you'd like to apply the refund to.
We then multiply the quantity value by the amount of each item and take the specified percent of that figure to calculate the refund.
The type represents the type of charge. Refer to Specifying the type of refund for more information.
reason
A string value that indicates the reason for the refund. Reason codes are arbitrary, searchable strings you may use to capture the reason for the refund.
metadata
Additional structured information for the object.

Example

You can refund a percentage of each line item in an Order. Digital River multiplies the quantity value by the cost of the item in the order (including taxes and landed costs) and then refunds the specified percent of that figure.
1
curl --location --request POST 'https://api.digitalriver.com/refunds' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"orderId": "178577530336",
6
"currency": "USD",
7
"items": [
8
{
9
"itemId": "97818230336",
10
"percent": 50.0,
11
"quantity": 2
12
},
13
{
14
"itemId": "97818240336",
15
"percent": 100.0,
16
"quantity": 3
17
}
18
],
19
"reason": "requested_by_customer"
20
}'
Copied!
A Refund object with a unique id is returned. The request specified a percent but the response returns an amount to refund. At both the order-level and item-level, the actual refundedAmount is 0.0 because the Refund remains in a state of pending.
1
{
2
"id": "re_45536e4c-9b81-455f-8731-a6f2419a4f19",
3
"createdTime": "2020-06-26T22:32:36Z",
4
"currency": "USD",
5
"items": [
6
{
7
"amount": 21.51,
8
"quantity": 2,
9
"refundedAmount": 0.0,
10
"skuId": "63472e51-4fd7-4865-a7c9-b2cfd103713d",
11
"itemId": "97818230336"
12
},
13
{
14
"amount": 96.77,
15
"quantity": 3,
16
"refundedAmount": 0.0,
17
"skuId": "bc8ee185-1d33-415c-b257-ee8f69ae3838",
18
"itemId": "97818240336"
19
}
20
],
21
"orderId": "178577530336",
22
"reason": "requested_by_customer",
23
"refundedAmount": 0.0,
24
"state": "pending",
25
"liveMode": false
26
}
Copied!

Checking the available refund amount

You can only create refunds that are less than or equal to the unrefunded amount remaining on the order. In other words, trying to refund more money than remains on the charge returns an error response.
So before issuing a refund, you should determine how much is available. The availableToRefundAmount attribute within the Order resource allows you to check this value.
The attribute records both completed and pending refunds. It exists at both the order-level and the item-level and its value is initially populated by Digital River. As you issue refunds, we update the value.
At a high level, Digital River calculates the availableToRefundAmountusing the following formula:
available to refund amount = total amount paid − (completed refund amount + pending refund amount)
The following shows a simplified Order object. Note that the availableToRefundAmount at the order-level and item-level. The refundedAmount records completed refunds.
In this case, no additional refunds could be issued at the item-level for the first line item in the items array because the availableToRefundAmount is 0.0. However, you could still create refunds on the second line item or at the order-level.
JSON
1
{
2
"id": "178487840336",
3
...
4
"totalAmount": 160.65,
5
...
6
"items": [
7
{
8
"id": "97696610336",
9
...
10
"amount": 90.0,
11
"quantity": 3,
12
"state": "fulfilled",
13
...
14
"availableToRefundAmount": 0.0
15
},
16
{
17
"id": "97696600336",
18
...
19
"amount": 40.0,
20
"quantity": 2,
21
"state": "fulfilled",
22
...
23
"availableToRefundAmount": 29.75
24
}
25
],
26
...
27
"refundedAmount": 130.9,
28
"state": "complete",
29
...
30
"availableToRefundAmount": 29.75,
31
..
32
}
Copied!

Specifying the type of refund

In a POST/refunds request, the type parameter allows you to issue order-level refunds on shipping, duty, tax, or importer_tax. At the product-level, you can use items[].type to issue refunds on shipping, fees, and duty.
For duties, fees, and shipping, both partial and full refunds are supported. However, you can only issue full tax refunds.

Best practice: Set percent rather than amount when issuing refunds on shipping

When you specify the type of refund in a POST/refunds, it's best practice not to reference the availableToRefundAmount to set the amount parameter. Instead, we recommended you specify a percent . The following example demonstrates why.
Let's say you've already issued refunds on a particular Order. The Order currently has an availableToRefundAmount of 25.55 and initial totalShipping costs of 5.0.
JSON
1
{
2
"id": "178552040336",
3
...
4
"totalShipping": 5.0,
5
"items": [
6
{
7
"id": "97778280336",
8
...
9
"availableToRefundAmount": 25.55
10
}
11
],
12
...
13
"refundedAmount": 28.0,
14
...
15
"availableToRefundAmount": 25.55,
16
...
17
}
Copied!
When you try to issue a refund, you set the type to shipping and the amount equal to what you thought remained unfunded on the shipping costs.
1
curl --location --request POST 'https://api.digitalriver.com/refunds' \
2
--header 'Authorization: Bearer <API_key>' \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"orderId": "178552040336",
6
"currency": "USD",
7
"type": "shipping",
8
"amount": 5.00,
9
"reason": "requested_by_customer"
10
}'
Copied!
In this case, however, you'll receive a 400 Bad Request response indicating the requested amount is greater than what's available.
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "invalid_parameter",
6
"parameter": "amountRequested",
7
"message": "The requested refund amount is greater than the available amount."
8
}
9
]
10
}
Copied!
This is because previous refunds were already issued on this Order. These refunds lowered the shipping costs available to refund, and you cannot specify an amount value that exceeds the total unrefunded shipping costs.
To avoid receiving this error response, simply specify a percent less than or equal to 100.

Refunding taxes

You can only issue full tax refunds. So when creating refunds with a type of tax or importer_tax you must set the percent parameter in the request to 100.
The importer_tax setting creates a refund of import duties.
If you set percent to any positive float less than 100, you'll generate a 400 Bad Request informing you that only full refunds are supported.
1
{
2
"type": "bad_request",
3
"errors": [
4
{
5
"code": "invalid_parameter",
6
"parameter": "percentRequested",
7
"message": "Only full tax refunds are supported."
8
}
9
]
10
}
Copied!
Last modified 7mo ago