Returns

Use the Returns API to:

  • Retrieve all returns for a specified order.
  • Return one or more line items in an order

See Caching Responses and Returns API for more information.

Resource URIs

All methods in this API require a full access token.

Methods


					Authorization: bearer your_access_token
Accept:application/json
			
					The request body should be empty.
			
					HTTP/1.1 200 OK
			
					{
  "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"
              }
            }
          ]
        }
      }
    ]
  }
}
			
					Authorization: bearer your_access_token
Accept:application/json
			
					{
	"return" : {
		"reason":"Duplicate Order",
		"comments":"Duplicate Order",
                "acceptELOD":"true",
		"returnLineItems":
		{
			"returnLineItem":
                         [
				{
					"lineItemQuantityIDs": [1,3,4]
					"lineItem":
					{
						"id":"your_line_item_ID",
						"quantity": 3,
                                        }
                                },
                                {
                                        "lineItemQuantityIDs": [1]
					"lineItem":
					{
						"id":"your_line_item_ID",
						"quantity": 1
					}
                                }

			]
		}
	}
}
			
					HTTP/1.1 200 OK
			
					{
  "returns": {
    "return": [
      {
        "id": <return_ID>,
        "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": <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$",
              "substitutionProduct":"substitution_product_ID",
              "lineItem": {
                "uri": "https://api.digitalriver.com/v1/shoppers/me/orders/order_ID/line-items/line_item_ID"
              "digitalRights":{
                "digitalRight":[
                 {
                   "lineItemQuantityId":"1",
                   "content":"ABC",
                   "type":"SERIAL_NUMBER"
                 },
                 {
                   "lineItemQuantityId":"1",
                   "content":"CBA",
                   "type":"SERIAL_NUMBER"
                 }
                ]
              }
            },
            {
              "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$",
              "substitutionProduct":"substitution_ID",
              "lineItem": {
                "uri": "https://api.digitalriver.com/v1/shoppers/me/orders/order_ID/line-items/line_item_ID"
              }
              "digitalRights":{
                "digitalRight":[
                {
                   "lineItemQuantityId":"1",
                   "content":"ABC",
                   "type":"SERIAL_NUMBER"
                },
                {
                   "lineItemQuantityId":"1",
                   "content":"CBA",
                   "type":"SERIAL_NUMBER"
                }
               ]
              }
            }
          ]
        }
      }
    ]
  }
}
			

formattedReturnLITotal

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

Request Body Parameters

Field
Description
Required
Validation
acceptELOD
Set to True when the shopper accepts the terms of the ELOD.
The required value must be either True or False.
If the value for "Are the site configurations complete for electronic letters of destruction?" is set to Yes in Big Blue, you must provide one of the following required values:
  • True
  • False
A value is not required if the site setting is set to No.
comments
The comments provided by the shopper.
No
Shopper comments are not required. Digital River adds Shopper Initiated Return as a prefix to a shopper’s comment.
lineItem.id
The line item ID within the order that the shopper wants to return.
Yes
Requires a valid line item ID within the order.
lineItem.quantity
The number of items to return for the specified line item.
Yes
The number must be greater than zero and less than or equal to the number of items eligible for return.
lineItemQuantityIds
The quantity IDs associated with the line item.
Yes
A line item quantity ID is only required for the following instances:
  • Individual Digital Rights–When you return a digital line item that is set up with individual digital rights.
  • Downloadable Line Item–When you return a downloadable line item that is set up with individual download URLs.
orderId
A valid order ID for the site that can be returned to the site.
Yes
Must be a valid order ID for the site.
reason
Shopper selected reason for the return.
Yes
The return reason must match a reason code configured for the API consumer’s site. See Reason Codes for more information.
returnLineItems
A grouping of one or more line items to return.
Yes
Requires at least one line item.

Response Body Parameters

Field
Data Type
Visibility
Description
comments
string
default
The comments provided by the shopper.
dateRefunded
date/string
default
The date when the product return was refunded. The possible values are as follows:
  • Date
  •  In Process
digitalRight
structured
default
The digital right associated with the line item.
digitalRight.content
string
default
The digital right information.
digitalRight.lineItemQualityId
string
default
The number of digital right line items.
digitalRight.type
string
default
The type of digital right. The possible types are as follows:
  • SERIAL_NUMBER
  • UNLOCK_CODE
digitalRights
structured
default
Digital rights manage the serial numbers and unlock codes that control shopper access to purchased software and other digital products.
formattedOutstandingTotal
string
expand
The outstandingTotal in locale currency format (for example, 19.14).
formattedRefundTotal
string
expand
The refundTotal in locale currency format (for example, $00.00).
formattedRequestTotal
string
expand
The requestTotal in locale currency format (for example, $19.14).
formattedReturnLITotal
string default The return line item value (for example $9.57).
generatedBy
string
default
The person who sent the return.
generationDate
date
default
The date when the return was created.
lineItem
link
default
A link to a specific line item ID. See the Line Items API for more information.
origin
string
default
Where the return originated. Possible values are as follows:
  • CUSTOMER_SERVICE
  • Shopper_Initiated
outstandingTotal
structured
expand
The outstanding total for the return.
outstandingTotal.currency
string
default The shopper’s preferred currency.
outstandingTotal.value
decimal
default The outstanding total value (for example, 19.14).
policy
string
default
The policy associated with this return. Possible values are as follows:
  • LOD
reason
string
default
Shopper selected reason for the return.
refundTotal
structured
expand
The refund information for the return.
refundTotal.currency
string
default The shopper’s preferred currency
refundTotal.value
decimal
default The refund value (for example $00.00).
return.id
string
default
the return ID.
returnLineItem
structured
expand
The return line item for the return.
returnLineItem.dueDate
date
default
The last day an item can be returned.
returnLineItem.offerId
string
default
The offer ID associated with the line item.
returnLineItem.offerDiscount
string
default
The offer discount percentage applied to the line item (for example, 10%).
returnLineItem.expectedQty
string
default
The number of line items expected to be returned.
returnLineItem.returnedQty
string
default
The actual number of line items returned.
returnLineItem.type
string
default
The type of returned line item. The possible values are as follows:
  • Download
returnLineItems.notes
string default Comments provided by the shopper.
returnLineItem.date
date
default
Specifies the date when the return was submitted.
returnLineItem.status
string default The status of the returned line item. The possible values are as follows:
  • PendingProductReturn
returnLineItem.returnLITotal
structured
expand
The requested information for the return.
returnLineItem.returnLITotal.currency
string
default The shopper’s preferred currency.
returnLineItem.returnLITotal.value
decimal
default The requested value (for example $19.14).
returnLineItems
structured
expand
The line items for the return.
requestedTotal
structured
expand
The line items for the return.
requestedTotal.currency
string
default the shopper's preferred currency.
requestedTotal.value
decimal
default The requested value (for example $19.14).
status
string
default
The status of the return. The possible status are as follows:
  • PendingProductReturn
substitutionProduct
string
default
The product ID that was substitued in place of the original product.
type
string
default
The type of return. The possible values are as follows:
  • LineItemLevelReturnProduct

Return Validation

Line items are not eligible for return when:

  • The site is not configured to allow self-service returns.
  • The entire quantity for the line item was previously returned.
  • 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 site settings specified by the API consumer.
  • The line item is not in a state that is compatible for 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.