Refunds

Learn how to use the Refunds resource.

Requirements

To use the Refunds resource, you need:

  • A client ID or API key. You must specify either an API Key or a token.

  • A customer's ID. You must specify either an API Key or a token.

  • A Global Commerce admin username and password. The password should be base-64 encoded when authenticating. The Global Commerce username requires the following roles (permissions):

    • Customer Service Representative

    • Customer Service Supervisor

    • Customer Service Director

Hint: You will need your Global Commerce user credentials when you use the Refunds API. For example, when using a Postman Collection you will need to provide these credentials in the csrUserName and csrPassword fields.

Reason codes

Reason codes are searchable alphanumeric strings of text that explains the reason for the refund. You can use standard Digital River reason codes or create a custom list of reason codes for this purpose and use the reason parameter to display this code in queries and responses.

A shopper can select a reason code that explains why they want a refund for the product. The reason codes in the request must match the reason codes configured for the API consumer’s site. The API consumer can map the description of the reason codes to the values they want to display to a shopper. API consumers can use Digital River's default reason codes or customize the reason codes to meet their specific needs. Contact your Digital River Representative if you want to customize your reason codes.

To view or configure standard Digital River reason codes and customized reason codes for your site, sign in to Global Commerce and follow the instructions in How to configure reason codes in the Global Commerce Help.

Standard refund reason codes

The following refund reason codes are available by default:

Reason Code

Description

Required/Optional

FRAUD

Fraud

Required

MISSING_ITEMS_FROM_ORDER

Missing Items From Order

Required

NEVER_RECEIVED

Never Received

Required

CANCELLED_BUT_SHIPPED

Cancelled But Shipped

Optional

CANT_DOWNLOAD

Cannot Download

Optional

CHARGEBACK_AVOIDANCE

DO NOT SELECT - System Initiated Chargeback Avoidance

Optional

CUSTOMER_ERROR

Customer Error

Optional

CUSTOMER_SATISFACTION_ISSUE

Customer Satisfaction Issue

Optional

DAMAGED_PRODUCT

Damaged Product

Optional

DELAYED_SHIPPING

Delayed Shipping

Optional

DUPLICATE_ORDER

Duplicate Order

Optional

FEE_CHARGED_INCORRECTLY

Fee Amount Charged Incorrectly

Optional

FEE_EXEMPT_CUSTOMER

Fee Exempt Customer

Optional

MATCH_PROMOTIONAL_PRICE

Match Promotional Price

Optional

ORDERED_WITHOUT_PERMISSION

Ordered Without Permission

Optional

ORDER_PROCESSING_ERROR

Order Processing Error

Optional

PHONE_ORDER_ERROR

Phone Order Error

Optional

PRODUCT_SHOULD_NOT_HAVE_FEE

Product Should Not Have a Fee

Optional

PRODUCT_TRIALWARE

Trialware

Optional

REFUSED_ORDER

Refused Order

Optional

TAX_EXEMPT

Tax Exempt

Optional

UNABLE_TO_SHIP_TO_COUNTRY

Unable To Ship To Country

Optional

UNDELIVERABLE_ADDRESS

Undeliverable Address

Optional

VENDOR_APPROVED_REFUND

Vendor Approved Refund

Optional

WRONG_PRODUCT

Wrong Product

Optional

Create a satisfaction refund

Create a satisfaction refund for the order like this where 999999999 is the orderId and you provide the customer' token:

URI
Request header
Request body
URI
POST /orders/999999999/refunds?token={the customer's token}
Request header
{
"Accept": "application/json"
}
Request body
{
"reason": "Damaged Product",
"comments": "Damaged Product upon receiving",
"type": "Order Level",
"category": "Order Adjustments",
"refundAmount": {
"currency": "USD",
"value": 20
}
}

A successful request returns a 200 response code:

Response code
Response header
Response body
Response code
200
Response header
{
"content-type": "application/json;charset=UTF-8"
}
Response body
No response. The body should be empty.

Retrieve the JSON schema for an order refund

Retrieve the JSON schema for a refund associated with an order like this where you provide the customer's token:

URI
Request header
Request body
URI
Get /orders/active/refunds?apiKey=active&token={the customer's
token}
Request header
{
"Accept": "application/json"
}
Request body
The request body should be empty.

A successful request returns a 200 response code:

URI
Request header
Request body
URI
200
Request header
{
"Accept": "application/json"
}
Request body
The request body should be empty.

Retrieve refunds available for an order

Retrieve the refunds available for a specific order like this where you provide the customer's token:

URI
Request header
Request body
URI
GET /orders/active/refunds-available?token={the customer's token}
Request header
{
"Accept": "application/json"
}
Request body
The request body should be empty.

A successful request returns a 200 response code:

Response code
Response header
Response body
Response code
200
Response header
{
"content-type": "application/json;charset=UTF-8"
}
Response body
{
"currency": "USD",
"lineItems": [
{
"lineItemId": "11035556604",
"price": {
"total": {
"amount": {
"value": 39.99,
"formattedValue": "$39.99"
},
"amountAvailableForRefund": {
"value": 39.99,
"formattedValue": "$39.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
}
},
"totalTax": {
"amount": {
"value": 3.99,
"formattedValue": "$3.99"
},
"amountAvailableForRefund": {
"value": 3.99,
"formattedValue": "$3.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
}
},
"totalShipping": {
"amount": {
"value": 4.99,
"formattedValue": "$4.99"
},
"amountAvailableForRefund": {
"value": 4.99,
"formattedValue": "$4.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
}
},
"totalShippingTax": null,
"totalDutiesAndTariffs": null,
"totalDutiesAndTariffsTax": null,
"totalFee": null,
"totalFeeTax": null
},
"product": {
"companyId": "demosft1",
"externalId": "ext 1234"
},
"status": null
},
{
"lineItemId": "11035556605",
"price": {
"total": {
"amount": {
"value": 39.99,
"formattedValue": "$39.99"
},
"amountAvailableForRefund": {
"value": 39.99,
"formattedValue": "$39.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
}
},
"totalTax": {
"amount": {
"value": 3.99,
"formattedValue": "$3.99"
},
"amountAvailableForRefund": {
"value": 3.99,
"formattedValue": "$3.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
}
},
"totalShipping": {
"amount": {
"value": 4.99,
"formattedValue": "$4.99"
},
"price": {
"total": {
"amount": {
"value": 39.99,
"formattedValue": "$39.99"
},
"amountAvailableForRefund": {
"value": 39.99,
"formattedValue": "$39.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
}
},
"totalTax": {
"amount": {
"value": 3.99,
"formattedValue": "$3.99"
},
"amountAvailableForRefund": {
"value": 3.99,
"formattedValue": "$3.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
}
},
"totalShipping": {
"amount": {
"value": 4.99,
"formattedValue": "$4.99"
},
"amountAvailableForRefund": {
"value": 4.99,
"formattedValue": "$4.99"
},
"amountRefunded": {
"value": 0.99,
"formattedValue": "$0.99"
}
},
"totalShippingTax": null,
"totalDutiesAndTariffs": null,
"totalDutiesAndTariffsTax": null,
"totalFee": null,
"totalFeeTax": null
},
"status": null
}

Error scenarios

Error Scenario

Error Message Description

API successfully executed

Operation Successful.

Cannot successfully resolve a site for a requisition

Unable to resolve the site for the requisition.

The provided Site ID was invalid or unresolved

It cannot resolve the requisition.

Input requisition line item ID is invalid or unresolved

Cannot resolve the line item.

Input refund type value is invalid

Invalid refund type.

Input refund reason value is invalid

Invalid refund reason.

Input refund category value is invalid

Invalid refund category.

Input currency type value is invalid

Currency in the request does not match with the requisition or lineItem.

Input currency code value is invalid

The currency code is invalid.

Input session ID value is invalid

The user session ID is invalid.

Input refund amount is 0 or less

Invalid refund amount.

Input refund amount is greater than the refundable amount

The requested refund amount is greater than the refundable amount.

Input refund amount is in incorrect format

Refund Amount is not a valid currency amount. valid format is (####.##).

Input fee type is invalid for a product level return (category: product_level_fee)

Unable to resolve fee type for the line item.

Requisition ID is empty

Requisition ID can not be empty.

Refund reason is empty

Refund Reason can not be empty.

Refund category is empty

The Refund Category can not be empty.

A product-level refund request fails to provide line item level details

Requisition Line Items can not be empty.

A product-level fee return fails to provide fee details

Line Item's Fee List can not be empty.

The site does not support satisfaction refund

The site is not allowed to accept satisfaction refund for the requisition.

A second refund is not allowed

This order does not allow a second refund. Additional refunds require that you perform a manual refund.

The user roles are invalid for this API

The user is not a Customer Service Representative/ Director/Supervisor.

The user roles are invalid for this API

The user is not a Customer Service Representative/ Director/Supervisor/InternalUser/Owner of the Order.

An unforeseen exception occurred

Unhandled runtime exception has occurred.