Returns

Learn how to use the Returns resource.

The Returns resource allows you to manage returns from your customers.

A return flow begins after the shopper signs in to an API client page. By signing in, the shopper authenticates themselves. When the shopper initiates a self-service return from a client-hosted page, such as a My Account page, the client then requests an authenticated session from Digital River and initiates a return request.

The following diagram shows how returns are processed.

Returns process diagram

Initiate an authenticated session

Send the following request to create an anonymous access token to identify the shopper session:

URI
URI
POST https://api.digitalriver.com/oauth20/token.json

Include your base64-encoded API key and secret in the request header. Include grant_type=client_credentials and the externalReferenceId in the request body. This Token API identifies a shopper session. A token consists of the access_token and the refresh_token. They correspond to session cookie and cookie in the browser. You can save the access_token and refresh_token in the application and use them in subsequent queries. The access_token expires after a specified interval (60 minutes by default in user session site settings in Global Commerce). The refresh_token expires after one year.

The expires_in property is the time-to-live (TTL) value for the access token. You can refresh the access token at any time.

Line items are not eligible for return when:

  • The site is not configured to allow self-service returns.

  • The shopper previously returned the entire quantity for the line item.

  • A satisfaction refund was already applied to the line item.

  • A satisfaction refund was already applied to the order.

  • The line item is outside of the return window that is configured within the site settings.

  • The API consumer can specify the return window.

  • The line item is not in a state that is compatible with a return to occur (for example, complete).

  • The order is in a state that is not eligible for a return.

  • The quantity the shopper wants to return is greater than the available quantity.

Caching responses

Caching responses reduces response time and consumes less network bandwidth. Cached responses improve performance by serving representations directly from the cache rather than the origin server.

You can configure caching in the Commerce API as follows:

  • Globally enable all cacheable resources

  • Enable per resource

  • Enable caching for related resources such as Offers and Product Offers

    resources

Only responses from the GET requests are cached. Caching is not enabled by default. For more information on enabling and configuring caching, contact your Digital River Representative.

Returnable-time period

Use the following formulas to determine if the product is within the returnable-time period:

  • Physical: Shipped Date + Return Period

  • Physical and Nothing Required Return Type: Order Submitted Date +

    Return Period

  • Digital, Download: Ordered Submitted Date + Return Period

Where:

  • Returned Period—The maximum number of days from the Shipped Date or Order Submitted Date in which a shopper can return a product. The default is 30 days. Your Digital River representative can update the Returned Period at the site level. The API does not provide this information. You cannot set the Returned Period at the product level.

  • Shipped Date—The date when the product shipped.

  • Order Submitted Date—The date when the shopper downloaded the digital product.

Reason codes

Reason codes are searchable alphanumeric strings of text that explains the reason for the return. 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 are returning a 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.

Note: Only Customer Service Configuration Managers can configure the reason codes.

Standard return reason codes

The following return 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

Digital Rights

A product’s digital rights can be either unique or identical.

  • Unique Digital Rights—a shopper receives a unique serial number for each unit ordered or purchased.

  • Identical Digital Rights—a shopper receives an identical serial number for every unit sold.

When a shopper returns an item that has unique digital rights, you revoke the digital rights for the line item and quantity. When the shopper has more than one digital rights ID for the line item, the shopper needs to select which digital rights ID to return.

Best Practices: We recommend that you display text that tells the shopper they must select the correct digital rights key because you will deactivate it once you process the return.

When a shopper returns an item that has identical digital rights, you revoke the digital rights when the shopper returns the entire quantity of the specified line item.

Best Practices: The shopper purchased a quantity of five items that have identical digital rights. You don’t revoke the digital rights until the shopper returns all five items.

If the product is Digital, and the Return Type is ELOD (Electronic Letter of Destruction), you must provide the shopper the ELOD online when returning a digital product and the return request should indicate whether the shopper accepted the ELOD. You must display the ELOD legal text to the shopper. If the shopper accepts the ELOD, Digital River will suppress the ELOD email.

Note: You must set the value for ELOD to true (ELOD = true).

You can configure the default setting for ELOD at the site level in Big Blue. The following must be true for a site to accept ELOD via the Returns API:

  • Are the site configurations complete for electronic letters of destruction? = Yes

Line items are not eligible for return when:

  • The site is not configured to allow self-service returns.

  • The shopper previously returned the entire quantity for the line item.

  • A satisfaction refund was already applied to the line item.

  • A satisfaction refund was already applied to the order.

  • The line item is outside of the return window that is configured within the site settings.

  • The API consumer can specify the return window.

  • The line item is not in a state that is compatible with a return to occur (for example, complete).

  • The order is in a state that is not eligible for a return.

  • The quantity the shopper wants to return is greater than the available quantity.

Setup

The following topics explain how to set up Global Commerce for the Returns API.

API endpoints

The API consumer interacts with the API through the following endpoints:

  • Production (PROD): https://api.digitalriver.com

  • Client Test Environment (CTE): https://api-cte-ext.digitalriver.com

PROD and CTE require your API key and secret (if applicable).

Setting up your site in Global Commerce

You must enable your site for self-service returns. To enable this feature, contact your Digital River Account Representative.

Returns API and the Customer Service return functionality

The Returns API has parity with the Customer Service return functionality in Global Commerce. You can expose the Returns API to initiate a return from a non-Digital River hosted page. Once the return has been accepted, the backend processing runs as expected. The Returns API does not provide additional functionality that is not supported in the Global Commerce.

Example: If a shopper purchases multiple quantities of the same PID (product identifier) or SKU (stock keeping unit) that has a unique identifier such as an IMEI (International Mobile Equipment Identity), Global Commerce does not allow a Customer Service Representative to select which IMEI the customer can return. Therefore, this is not supported in the Returns API as downstream processing will be affected.

Retrieve all returns for a specified order

Retrieve all returns for a specified order where 999999999 is the orderId.

Requirement: Create an OAuth token before invoking the Returns API.

URI
Request header
Request body
URI
GET /v1/shoppers/me/orders/9999999999/returns
Request header
Accept: application/json Authorization: bearer your_access_token
Request body
The request body should be empty.

A successful request returns a 200 response code:

Response header
Response body
Response header
HTTP/1.1 200 OK
Response body
{
"returns": {
"return": [
{
"id": 9999999999,
"reason": "PHONE_ORDER_ERROR",
"comments": "hello change it",
"type": "LineItemLevelReturnProduct",
"status": "PendingProductReturn",
"generationDate": "2016-10-17T15:00:24.000Z",
"generatedBy": "aianand",
"origin": "CUSTOMER_SERVICE",
"policy": "LOD",
"dateRefunded": "In Process",
"refundTotal": {
"currency": "USD",
"value": 0
},
"formattedRefundTotal": "0.00$",
"outstandingTotal": {
"currency": "USD",
"value": 19.14
},
"formattedOutstandingTotal": "19.14$",
"requestedTotal": {
"currency": "USD",
"value": 19.14
},
"formattedRequestedTotal": "19.14$",
"returnLineItems": {
"returnLineItem": [
{
"dueDate": "2016-10-25T04:59:59.000Z",
"offerId": 464443297,
"offerDiscount": "10%",
"expectedQty": 1,
"returnedQty": 0,
"type": "Download",
"notes": "LOD_OPEN2016-10-25T04:59:59.000Z",
"date": "2016-10-17T15:00:25.000Z",
"status": "PendingProductReturn",
"returnLITotal": {
"currency": "USD",
"value": 9.57
},
"formattedReturnLITotal": "9.57$",
"lineItem": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/orders/order_ID/line-items/lin_item_ID"
}
},
{
"dueDate": "2016-10-25T04:59:59.000Z",
"offerId": offer_ID,
"offerDiscount": "10%",
"expectedQty": 1,
"returnedQty": 0,
"type": "Download",
"notes": "LOD_OPEN2016-10-25T04:59:59.000Z",
"date": "2016-10-17T15:00:25.000Z",
"status": "PendingProductReturn",
"returnLITotal": {
"currency": "USD",
"value": 9.57
},
"formattedReturnLITotal": "9.57$",
"lineItem": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/orders/order_ID/line-items/line_item_ID"
}
}
]
}
}
]
}
}

Request the return of one or more line items in an order

Request the return of one or more line items in a specified order where 999999999 is the orderId.

URI
Request header
Request body
URI
POST /v1/shoppers/me/orders/9999999999/returns
Request header
Accept: application/json Authorization: bearer your_
access_token
Request body
{
"return": {
"reason": "DUPLICATE_ORDER",
"comments": "Duplicate Order",
"acceptELOD": "true",
"returnLineItems": {
"returnLineItem": [
{
"lineItemQuantityIDs": [
1
],
"lineItem": {
"id": "123",
"quantity": 1
}
}
]
}
}
}

A successful request returns a 200 response code:

Response header
Response body
Response header
HTTP/1.1 200 OK
Response body
{
"returns": [
{
"return": [
{
"id": 6654727889,
"reason": "DUPLICATE_ORDER",
"comments": "Shopper initiated self service return-",
"type": "LineItemLevelReturnProduct",
"status": "RefundedWithoutReturn",
"generationDate": "2020-01-30T17:37:09.000Z",
"generatedBy": "56066c6b-139b-47ff-9b07-1c799c10ea75",
"origin": "SHOPPER",
"policy": "LOD",
"dateRefunded": "In Process",
"refundTotal": {
"currency": "USD",
"value": 0
},
"formattedRefundTotal": "0.00USD",
"outstandingTotal": {
"currency": "USD",
"value": 107.53
},
"formattedOutstandingTotal": "107.53USD",
"requestedTotal": {
"currency": "USD",
"value": 107.53
},
"formattedRequestedTotal": "107.53USD",
"returnLineItems": {
"returnLineItem": [
{
"dueDate": "2020-02-07T05:59:59.000Z",
"expectedQty": 1,
"returnedQty": 1,
"type": 100409,
"notes": "LOD_REFUNDED-2020-02-07T05:59:59.000Z",
"date": "2020-01-30T17:37:09.000Z",
"status": "RefundedWithoutReturn",
"returnLITotal": {
"currency": "USD",
"value": 107.53
},
"formattedReturnLITotal": "107.53USD",
"lineItem": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/orders/793374880082/line-items/793451150082"
}
}
]
}
}
]
}
]
}

formattedReturnLITotal

The value for formattedReturnLITotal in the Response Body example for POST /shoppers/me/orders/{orderId}/returns is based on the results of a get order request. The format will be either "formattedReturnLITotal":"50.00$" or "formattedReturnLITotal":"$50.00" as the displayed format of the get order request. The value for the date uses the UTC format for the date and time zone.

Return validation

Line items are not eligible for return when:

  • The site is not configured to allow self-service returns.

  • The customer previously returned the entire quantity for the line item.

  • A satisfaction refund was already applied to the line item.

  • A satisfaction refund was already applied to the order.

  • The line item is outside of the configured return window specified in the site settings by the API consumer.

  • The line item is not in a state that is compatible with a return to occur (for example, complete).

  • The Order is in a state that is not eligible for a return.

  • The quantity the shopper wants to return is greater than the available quantity.

  • The line item is a subscription type.