Returns API

This topic describes the following best practices for the Returns API:

See also Caching Responses for additional information.

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


  • Returned Period—the maximum number of days from the Shipped Date or Order Submitted Date in which a product can be returned. The default is 30 days. Your Digital River representative can update the Returned Period at the site level. This information is not provided in the API. The Returned Period cannot be set at the product level.
  • Shipped Date—the date on which the product shipped.
  • Order Submitted Date—the date on which the digital download was submitted.

Reason Codes

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.

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, the Digital Rights for the line item and quantity are revoked. 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.  We recommend that you display text to the shopper that explains they must select the correct Digital Rights key as it will be deactivated upon the processing of the return.

When a shopper returns an item that has identical Digital Rights, the Digital Rights are revoked when the shopper returns the entire quantity of the specified line item.  For example, the shopper purchased a quantity of five items which have identical Digital Rights, the Digital Rights are not revoked 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 or not the shopper accepted the ELOD. You must display the ELOD legal text to the shopper. If shopper accepts the ELOD, Digital River will suppress the ELOD email.


The value for ELOD must be set to true (ELOD = true).

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

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