eBay Post-Order APIVersion 2

Search Returns

GET /post-order/v2/return/search

Use this call to retrieve the details on one or more return requests, or a summary of return requests per user. This call supports several filters, supplied as query parameters, that allow you to restrict results by date, return status, return type, or by listing. If you use more than one filter type in the call, Boolean AND logic is applied to the result set. Boolean OR logic is used for conditions within a filter.

Input

See also Samples.

Resource URI (production)

GET https://api.ebay.com/post-order/v2/return/search?
  creation_date_range_from=string&
  creation_date_range_to=string&
  item_id=string&
  limit=integer&
  offset=integer&
  order_id=string&
  return_id=string&
  return_state=token&
  role=token&
  sort=ReturnSortField&
  states=token&
  transaction_id=string

URI parameters

Parameter Type Required? Meaning
creation_date_range_from string Optional Specify the creation_date_range_from and creation_date_range_to query parameters if you want to retrieve return requests that were created during a specific period of time.

Specify the starting date for your date range using the creation_date_range_from parameter. The date specified must be older than the creation_date_range_to timestamp and it cannot be set to more than 18 months in the past. If you specify a creation_date_range_from value, but do not specify a creation_date_range_to value, the call returns all return requests created at or after the specified timestamp and goes forward for the following 90 days. Use an ISO date format to specify the timestamp. For example: 2015-05-15T03:52:39.000Z.
creation_date_range_to string Optional Specify the creation_date_range_from and creation_date_range_to query parameters if you want to retrieve return requests that were created during a specific period of time.

Specify the ending date for your date range using the creation_date_range_to parameter. The date specified must be more recent than the creation_date_range_from. If you specify a creation_date_range_to value, but do not specify a creation_date_range_from, the call returns all return requests created at or before the specified timestamp, goes backwards for the preceding 90 days. Use an ISO date format to specify the timestamp. For example: 2015-07-15T03:52:39.000Z.
item_id string Optional The unique eBay-assigned ID of a listing. Supply the item_id query parameter if you want to see any and all return requests opened against this listing.
limit integer Optional This query parameter specifies the maximum number of return requests to retrieve in a single request. This number specifies the number of entries returned per result 'page' and the complete result set consists of one or more pages of entries.

This value, along with the number of returns that match the input criteria, determines the total pages contained in the complete result set (see paginationOutput.totalPages). The number of return requests returned (and those not returned from the result set) is determined by the settings specified in the sort parameter.

The maximum value for this parameter is 200 and the default value is 25 return requests per page.
offset integer Optional This query parameter specifies the page from the result set to return from the call.

Specify a positive value equal to or lower than the number of pages available (which you determine by examining the results in the paginationOutput container of your initial call). If you don't supply this parameter, the request returns the first page of results from the result set.
order_id string --- The unique eBay-assigned ID for the order associated with the return request.
return_id string --- Use this query parameter to return a specific return, as identified by its unique returnId.
return_state token Optional Specify this query parameter if you want to retrieve return requests that are currently in a specific return state or "status".

See ReturnCountFilterEnum for the list of values you can use in this parameter.

If you include this query parameter but don't set its value, all open return requests are returned.
role token --- Use this query parameter to get return actions that were initiated by either the buyer or the seller.
sort string Optional This query parameter specifies how to sort the response. The returned entries can be sorted by return creation date, return reason, return status, estimated or actual refund amount, refund due date, or return ID. To retrieve results in ascending order, use sort=enumValue. To retrieve results in descending order, add an negative sign (-) before the enumeration value, like this: sort=-enumValue.

Applicable values are from ReturnSortField.
states token --- The "state" of the return request.

See ReturnCountFilterEnum for the list of values you can use in this parameter.
transaction_id string Optional The unique eBay-assigned ID of a line item in an order. Specify this query parameter if you want detailed information on a specific return request that was filed against the order line item indicated by this field.

If you want to retrieve results that are outside the default time period, include a value in the item_id query parameter. If you do supply values in these parameters, the values supplied in other query parameters are ignored.


HTTP request headers

All requests made to eBay REST operations require you to provide the authorization HTTP header for authentication.
See HTTP request headers for details.



Authorization

This call uses standard authorization tokens. See Making a Call for details.

Payload model

This call has no request payload.


Output

See also Samples.

Payload model

Note: For information about the error fields and how to work with them, see Error Handling.

The following lists all fields that could be included in the response.

Supported response formats: application/json, application/xml

For more information:
- See GetSummaryResponse for a description of the response structure
- See the following table for descriptions of each of the data elements returned
- See the Samples for an example of the response format

{ /* GetSummaryResponse */
"countSummary": [
    { /* CountSummaryType */
    "count": integer,
    "type": token
    }
    /* More CountSummaryType nodes here */
  ],
"members": [
    { /* ReturnSummaryType */
    "buyerAvailableOptions": [
        { /* AvailableOptionType */
        "actionType": token,
        "actionURL": string
        }
        /* More AvailableOptionType nodes here */
      ],
    "buyerLoginName": string,
    "buyerResponseDue":
        { /* ReturnResponseDueType */
        "activityDue": token,
        "respondByDate":
            { /* DateTime */
            "formattedValue": string,
            "value": datetime
            }
        },
    "buyerTotalRefund":
        { /* TotalRefundAmountType */
        "actualRefundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "value": number
            },
        "estimatedRefundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "value": number
            }
        },
    "creationInfo":
        { /* ReturnCreationInfoType */
        "comments":
            { /* Text */
            "content": string,
            "language": string,
            "translatedFromContent": string,
            "translatedFromLanguage": string
            },
        "creationDate":
            { /* DateTime */
            "formattedValue": string,
            "value": datetime
            },
        "item":
            { /* ReturnItemType */
            "itemId": string,
            "returnQuantity": integer,
            "transactionId": string
            },
        "reason": token,
        "reasonType": token,
        "type": token
        },
    "currentType": token,
    "dispositionRuleTriggered": [
        token
        /* More token nodes here */
      ],
    "escalationInfo":
        { /* EscalationInfoType */
        "buyerEscalationEligibilityInfo":
            { /* EscalationEligibilityInfo */
            "eligible": boolean,
            "endTime":
                { /* DateTime */
                "formattedValue": string,
                "value": datetime
                },
            "startTime":
                { /* DateTime */
                "formattedValue": string,
                "value": datetime
                }
            },
        "caseId": string,
        "sellerEscalationEligibilityInfo":
            { /* EscalationEligibilityInfo */
            "eligible": boolean,
            "endTime":
                { /* DateTime */
                "formattedValue": string,
                "value": datetime
                },
            "startTime":
                { /* DateTime */
                "formattedValue": string,
                "value": datetime
                }
            }
        },
    "orderId": string,
    "returnId": string,
    "returnPolicy":
        { /* ReturnPolicyType */
        "rmaRequired": boolean
        },
    "sellerAvailableOptions": [
        { /* AvailableOptionType */
        "actionType": token,
        "actionURL": string
        }
        /* More AvailableOptionType nodes here */
      ],
    "sellerLoginName": string,
    "sellerResponseDue":
        { /* ReturnResponseDueType */
        "activityDue": token,
        "respondByDate":
            { /* DateTime */
            "formattedValue": string,
            "value": datetime
            }
        },
    "sellerTotalRefund":
        { /* TotalRefundAmountType */
        "actualRefundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "value": number
            },
        "estimatedRefundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "value": number
            }
        },
    "state": token,
    "status": token,
    "timeoutDate":
        { /* DateTime */
        "formattedValue": string,
        "value": datetime
        }
    }
    /* More ReturnSummaryType nodes here */
  ],
"paginationOutput":
    { /* PaginationOutput */
    "limit": integer,
    "offset": integer,
    "totalEntries": integer,
    "totalPages": integer
    },
"total": integer
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
countSummary array of CountSummaryType Always This container holds a count of return requests in different states. A separate count and type pair is returned for each return request state, such as 'ALL_OPEN', 'RETURN_STARTED', and 'ITEM_DELIVERED'. The return request states that are returned depend on the use of the return_state query parameter. If this query parameter is omitted in the call request, every active return request in all states are returned. However, if this query parameter is used, the response will include only those return requests in the specified state.
countSummary.count integer Always This integer value indicates how many return requests in the return state indicated by the corresponding countSummary.type value were returned in the call response.
countSummary.type token Always This enumeration value indicates the return request status that is being counted through the corresponding countSummary.count field. Return request states include 'ALL_OPEN', 'CLOSED', 'ITEM_SHIPPED', and 'ITEM_DELIVERED'. For a complete list of values and their descriptions, see ReturnCountFilterEnum.

Applicable values: See ReturnCountFilterEnum
members array of ReturnSummaryType Conditionally This container is an array of return requests that match the query parameters in the call request.
members.buyerAvailableOptions array of AvailableOptionType Conditionally This container consists of the next option(s) that are available to the buyer to move the return request to the next stage. A buyerAvailableOptions container will be returned for each option that is available to the buyer.
members.buyerAvailableOptions
  .actionType
token Always This token value informs the buyer or seller what the next action is to move the return request to the next stage. Note that not all values in the ActivityOptionEnum type are applicable and possibly returned in this field.

Applicable values: See ActivityOptionEnum
members.buyerAvailableOptions
  .actionURL
string Conditionally This field contains the URL to an eBay page where the buyer or seller can take their next action (specified in the actionType field) in a return request. This field will only be returned if there is an eBay page associated with the next action.
members.buyerLoginName string Conditionally This string value is the eBay user name of the buyer.
members.buyerResponseDue ReturnResponseDueType Conditionally This container indicates when the next buyer response on the return is due.
members.buyerResponseDue
  .activityDue
token Conditionally This value informs the buyer or seller what the next action is to move the return request to the next stage.

Applicable values: See ActivityOptionEnum
members.buyerResponseDue
  .respondByDate
DateTime Conditionally This timestamp indicates the deadline for when a buyer or seller must perform the next action (indicated in activityDue field) on the return request. This field will only be returned if there is a deadline associated with the next action.
members.buyerResponseDue
  .respondByDate.formattedValue
string Conditionally Reserved for future use.
members.buyerResponseDue
  .respondByDate.value
datetime Conditionally The date and time defining the start or end of an action or event.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2020-08-20T00:00:00.000Z
members.buyerTotalRefund TotalRefundAmountType Conditionally This container returns the total refund amount for the buyer. The call returns either the estimated (pre-refund) amount due or the actual (post-refund) amount paid.

In some cases, the buyerTotalRefund differs from the sellerTotalRefund because the buyer may receive refunds from sources other than the seller. This can happen, for example, when eBay collects and remits state sales taxes for the items being refunded.
members.buyerTotalRefund
  .actualRefundAmount
Amount Conditionally This container is returned after a refund has been issued and shows the actual refund amount paid to the buyer.
members.buyerTotalRefund
  .actualRefundAmount
  .convertedFromCurrency
string Conditionally This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
Code so that your app gracefully handles any future changes to this list.
members.buyerTotalRefund
  .actualRefundAmount
  .convertedFromValue
number Conditionally This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
members.buyerTotalRefund
  .actualRefundAmount.currency
string Conditionally This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
Code so that your app gracefully handles any future changes to this list.
members.buyerTotalRefund
  .actualRefundAmount.value
number Conditionally The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
members.buyerTotalRefund
  .estimatedRefundAmount
Amount Always Returned before a refund has been issued, this container shows the estimated refund amount due to the buyer.
members.buyerTotalRefund
  .estimatedRefundAmount
  .convertedFromCurrency
string Conditionally This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
Code so that your app gracefully handles any future changes to this list.
members.buyerTotalRefund
  .estimatedRefundAmount
  .convertedFromValue
number Conditionally This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
members.buyerTotalRefund
  .estimatedRefundAmount
  .currency
string Conditionally This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
Code so that your app gracefully handles any future changes to this list.
members.buyerTotalRefund
  .estimatedRefundAmount.value
number Conditionally The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
members.creationInfo ReturnCreationInfoType Always This container provides details about the buyer's return request, including the order line item (and quantity) that is being returned, the reason for the return, and the buyer's preference to either get money back for item or to get a replacement item from the seller.
members.creationInfo.comments Text Conditionally If provided by the buyer at return creation time, this container provides more information to the seller about why a return is being requested. This container is only returned if the buyer made a comment at the time of creating the return request or draft.
members.creationInfo.comments
  .content
string Conditionally This field displays the actual textual content in the language specified in the language field. This field is always used for containers using the Text type.
members.creationInfo.comments
  .language
string Conditionally This two-letter code indicates the language used to display the content in the content field. The language will default to the language used on the eBay site if a specific language is not specified through the Accept-Language HTTP header. This field is always used for containers using the Text type.

Applicable values are from LanguageEnum:See language.
Code so that your app gracefully handles any future changes to this list.
members.creationInfo.comments
  .translatedFromContent
string Conditionally If language translation/localization is required, this field displays the actual textual content in the language specified in the translatedFromLanguage field. If language translation was not required, this field is not applicable.
members.creationInfo.comments
  .translatedFromLanguage
string Conditionally If language translation/localization is required, this two-letter code indicates the language used to display the content in the translatedFromContent field. If language translation was not required, this field is not applicable.

Applicable values are from LanguageEnum:See translatedFromLanguage.
Code so that your app gracefully handles any future changes to this list.
members.creationInfo
  .creationDate
DateTime Always This timestamp indicates the date/time when the return request was created.
members.creationInfo
  .creationDate.formattedValue
string Conditionally Reserved for future use.
members.creationInfo
  .creationDate.value
datetime Conditionally The date and time defining the start or end of an action or event.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2020-08-20T00:00:00.000Z
members.creationInfo.item ReturnItemType Always This container provides information on the return item, including listing ID, listing title, order line item ID, and the quantity of the line item that is being returned.
members.creationInfo.item
  .itemId
string Always The unique eBay-assigned ID for a item in an order.

Note: This field in conjunction with the transactionId field uniquely identify a line item within an order.

members.creationInfo.item
  .returnQuantity
integer Always This integer value indicates the quantity of the line item being returned. This number is generally 1, unless the buyer bought multiple quantity of the item in a multiple-quantity, fixed-price listing.
members.creationInfo.item
  .transactionId
string Always The unique eBay-assigned ID of the order (transaction) associated with the return.
members.creationInfo.reason token Always This enumerated value indicates the buyer's reason for creating a return request or draft.

Applicable values: See ReturnReasonEnum
members.creationInfo
  .reasonType
token Conditionally This value indicates the reason the buyer is opening the return request.

Applicable values: See ReturnReasonTypeEnum
members.creationInfo.type token Always This enumerated value indicates the buyer's desired outcome - money back for the order or a replacement item (in the case of a SNAD item).

Applicable values: See ReturnTypeEnum
members.currentType token Conditionally This enumerated value indicates the buyer's desired outcome - money back for the order or a replacement item (in the case of a SNAD item).

Applicable values: See ReturnTypeEnum
members
  .dispositionRuleTriggered
array of token Conditionally This enumerated value indicates the type of disposition rule triggered by the return request. More than one dispositionRuleTriggered field may be returned.
members.escalationInfo EscalationInfoType Conditionally This container provides information on whether or not the buyer or seller is eligible to escalate a return request to a case, and if a return request was escalated, a caseId can be found in this container.
members.escalationInfo
  .buyerEscalationEligibilityInfo
EscalationEligibilityInfo Always This container indicates if the buyer is eligible to escalate the return request into a return case. If the buyer is eligible to escalate the return request into a return case, the time window during which this buyer must perform this action is returned under this container.
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .eligible
boolean Always This Boolean value indicates whether or not the buyer or seller is eligible to escalate the case. If the value is 'true', the time window in which the buyer or seller can escalate the case is found in the startTime and endTime fields.
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .endTime
DateTime Conditionally This timestamp provides the deadline in which the buyer or seller may escalate the case. As soon as this time expires, the buyer or seller may no longer escalate the case. This field will not be returned if the value of the eligible field is 'false'.
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .endTime.formattedValue
string Conditionally Reserved for future use.
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .endTime.value
datetime Conditionally The date and time defining the start or end of an action or event.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2020-08-20T00:00:00.000Z
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .startTime
DateTime Conditionally This timestamp provides the earliest date in which the buyer or seller may escalate the case. As soon as this time arrives, up until the time shown in the end field, the buyer or seller is eligible to escalate the case. This field will not be returned if the value of the eligible field is 'false'.
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .startTime.formattedValue
string Conditionally Reserved for future use.
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .startTime.value
datetime Conditionally The date and time defining the start or end of an action or event.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2020-08-20T00:00:00.000Z
members.escalationInfo.caseId string Conditionally The unique eBay-assigned ID of an eBay case. This field will only be returned if the return request was successfully escalated to a return case.
members.escalationInfo
  .sellerEscalationEligibilityInfo
EscalationEligibilityInfo Always This container indicates if the seller is eligible to escalate the return request into a return case. If the seller is eligible to escalate the return request into a return case, the time window during which this seller must perform this action is returned under this container.
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .eligible
boolean Always This Boolean value indicates whether or not the buyer or seller is eligible to escalate the case. If the value is 'true', the time window in which the buyer or seller can escalate the case is found in the startTime and endTime fields.
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .endTime
DateTime Conditionally This timestamp provides the deadline in which the buyer or seller may escalate the case. As soon as this time expires, the buyer or seller may no longer escalate the case. This field will not be returned if the value of the eligible field is 'false'.
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .endTime.formattedValue
string Conditionally Reserved for future use.
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .endTime.value
datetime Conditionally The date and time defining the start or end of an action or event.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2020-08-20T00:00:00.000Z
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .startTime
DateTime Conditionally This timestamp provides the earliest date in which the buyer or seller may escalate the case. As soon as this time arrives, up until the time shown in the end field, the buyer or seller is eligible to escalate the case. This field will not be returned if the value of the eligible field is 'false'.
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .startTime.formattedValue
string Conditionally Reserved for future use.
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .startTime.value
datetime Conditionally The date and time defining the start or end of an action or event.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2020-08-20T00:00:00.000Z
members.orderId string Conditionally The unique eBay-assigned ID of the order being returned.
members.returnId string Conditionally The unique eBay-assigned ID of the return request.
members.returnPolicy ReturnPolicyType Conditionally This container indicates whether or not the seller is required to provide an RMA (return merchandise authorization) number to the buyer. The seller can use the POST /post-order/v2/return/{returnId}/decide call to provide the buyer with the RMA number.
members.returnPolicy
  .rmaRequired
boolean Conditionally This Boolean field is returned as true if the seller is expected to provide a return merchandise authorization (RMA) number to the buyer before the buyer return ships the order line item. The seller can use the POST /post-order/v2/return/{returnId}/decide call to provide the buyer with the RMA number for the item.
members.sellerAvailableOptions array of AvailableOptionType Conditionally This container consists of the next option(s) that are available to the seller to move the return request to the next stage. A sellerAvailableOptions container will be returned for each option that is available to the seller.
members.sellerAvailableOptions
  .actionType
token Always This token value informs the buyer or seller what the next action is to move the return request to the next stage. Note that not all values in the ActivityOptionEnum type are applicable and possibly returned in this field.

Applicable values: See ActivityOptionEnum
members.sellerAvailableOptions
  .actionURL
string Conditionally This field contains the URL to an eBay page where the buyer or seller can take their next action (specified in the actionType field) in a return request. This field will only be returned if there is an eBay page associated with the next action.
members.sellerLoginName string Conditionally This string value is the eBay user name of the seller.
members.sellerResponseDue ReturnResponseDueType Conditionally This container indicates when the next seller response on the return is due.
members.sellerResponseDue
  .activityDue
token Conditionally This value informs the buyer or seller what the next action is to move the return request to the next stage.

Applicable values: See ActivityOptionEnum
members.sellerResponseDue
  .respondByDate
DateTime Conditionally This timestamp indicates the deadline for when a buyer or seller must perform the next action (indicated in activityDue field) on the return request. This field will only be returned if there is a deadline associated with the next action.
members.sellerResponseDue
  .respondByDate.formattedValue
string Conditionally Reserved for future use.
members.sellerResponseDue
  .respondByDate.value
datetime Conditionally The date and time defining the start or end of an action or event.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2020-08-20T00:00:00.000Z
members.sellerTotalRefund TotalRefundAmountType Conditionally This container returns the total refund amount from the seller to the buyer. The call returns either the estimated (pre-refund) amount due or the actual (post-refund) amount paid.
members.sellerTotalRefund
  .actualRefundAmount
Amount Conditionally This container is returned after a refund has been issued and shows the actual refund amount paid to the buyer.
members.sellerTotalRefund
  .actualRefundAmount
  .convertedFromCurrency
string Conditionally This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
Code so that your app gracefully handles any future changes to this list.
members.sellerTotalRefund
  .actualRefundAmount
  .convertedFromValue
number Conditionally This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
members.sellerTotalRefund
  .actualRefundAmount.currency
string Conditionally This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
Code so that your app gracefully handles any future changes to this list.
members.sellerTotalRefund
  .actualRefundAmount.value
number Conditionally The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
members.sellerTotalRefund
  .estimatedRefundAmount
Amount Always Returned before a refund has been issued, this container shows the estimated refund amount due to the buyer.
members.sellerTotalRefund
  .estimatedRefundAmount
  .convertedFromCurrency
string Conditionally This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
Code so that your app gracefully handles any future changes to this list.
members.sellerTotalRefund
  .estimatedRefundAmount
  .convertedFromValue
number Conditionally This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
members.sellerTotalRefund
  .estimatedRefundAmount
  .currency
string Conditionally This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
Code so that your app gracefully handles any future changes to this list.
members.sellerTotalRefund
  .estimatedRefundAmount.value
number Conditionally The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
members.state token Conditionally Indicates the current state of the return.

Applicable values: See ReturnStateEnum
members.status token Conditionally Indicates the current status of the return request.

Applicable values: See ReturnStatusEnum
members.timeoutDate DateTime Conditionally This timestamp indicates the date and time the seller's response for return request expires. At this time, the return request is the closed due to the seller's non-response.
members.timeoutDate
  .formattedValue
string Conditionally Reserved for future use.
members.timeoutDate.value datetime Conditionally The date and time defining the start or end of an action or event.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2020-08-20T00:00:00.000Z
paginationOutput PaginationOutput Always This container consists of metadata related to the current response page. It contains the page number and the return entries per page, as well as the total amount of response pages and return entries.
paginationOutput.limit integer Always The maximum number of entries to return per request. The value of the totalEntries field divided by the value of this field determines the value of the totalPages field. This value cannot be higher than the number of entries that match the input criteria.
paginationOutput.offset integer Always Identifies the specific page of data to be returned by the request.

The total number of pages in the result set is determined by the total number of entries matching the request criteria (totalEntries), divided by the number of entries to display per page of data (as specified by limit). If there are multiple pages of entries to view (see totalPages), make multiple requests to view all entries and increment the page number by 1 in each subsequent request.

Default: 1
paginationOutput.totalEntries integer Always The total number of entries that match the current input criteria of the request. This value divided by the value of the limit field determines the value of the totalPages field.

Once this number of response set is known, you can modify the input to get the results you desire.
paginationOutput.totalPages integer Always The total number of pages of entries that match the current input criteria of the request.

This value is determined by dividing the value of the totalEntries field by the value of the limit field. If totalPages is more than 1, this call must be issued multiple times to view all result pages, with the page number value being incremented by 1 in each subsequent call.
total integer Conditionally This field is not currently used. The total number of return entries and the number of return entries on the current page are shown in the paginationOutput container.



Samples

New to making API calls? Please see Making a Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample: Basic Call

Search for returns

Description

This call allows for a search of return requests. Query parameters allow for flexibility in the search. For this particular call sample, a seller is looking for all return requests that have just been initiated by their order partners (buyers).

Input

The seller is looking for all return requests that have just been initiated, so the seller includes the return_state query parameter and sets its value to RETURN_STARTED.

URL format. See also the non-wrapped version of this URL.

GET https://api.ebay.com/post-order/v2/return/search?
   return_state=RETURN_STARTED

Output

Based on the response, there are currently three return requests that have just been initiated by buyers. The countSummary container captures this fact. Detailed information on the three return requests can be found under the returns container. Each return request is identifier by its returnId value. For two of the return requests, the buyers are asking for their money back, as indicated in the currentType fields. The last return request in the response shows that the buyer noted the received item as being defective (see the creationInfo.reason field) and that buyer wants a replacement item, as indicated by the corresponding currentType field.

For all three of these return requests, the seller's next response will be to either accept or deny the return request, or send the buyer a message. These available options are captured in the sellerAvailableOptions container.

JSON format.
{ /* GetSummaryResponse */
"countSummary": [
    { 
    "count": 3,
    "type": RETURN_STARTED
    }
  ],
"returns": [
    { 
    "returnId": "5000080362",
    "currentType": MONEY_BACK,
    "state": RETURN_REQUESTED,
    "status": RETURN_REQUESTED,
    "creationInfo":
				{ 
				"creationDate":
						{ 
						"value": "2015-08-05T20:18:17.000Z"
						},
				"item":
						{ 
						"itemId": "190004540256",
						"transactionId": "8154427009",
						"returnQuantity": 1,
						},
				"reason": ARRIVED_DAMAGED,
				"type": MONEY_BACK
        },
    "buyerLoginName": "buyer_321",
    "sellerLoginName": "seller_564",
    "buyerTotalRefund":
        { 
        "estimatedRefundAmount":
            { 
            "value": 27.5
            "currency": USD,
            }
        },
    "escalationInfo":
        { 
        "buyerEscalationEligibilityInfo":
            { 
            "eligible": true,
            "startTime":
								{ 
								"value": "2015-08-05T20:18:17.000Z"
                }
            "endTime":
                { 
                "value": "2015-08-19T20:18:17.000Z"
                }
            },
        "sellerEscalationEligibilityInfo":
            { 
           	"eligible": true,
							 "startTime":
									{ 
									"value": "2015-08-05T20:18:17.000Z"
									 }
							 "endTime":
									 { 
									 "value": "2015-08-19T20:18:17.000Z"
                }
            }
        },
    "sellerAvailableOptions": [
        { 
        "actionType": SELLER_APPROVE_REQUEST
        },
        { 
				"actionType": SELLER_DECLINE_REQUEST
        },
        { 
				"actionType": SELLER_SEND_MESSAGE
        }
      ],
    "sellerResponseDue":
        { 
        "activityDue": SELLER_APPROVE_REQUEST,
        "respondByDate":
            { 
            "value": "2015-08-09T20:18:17.000Z"
            }
        },
    "sellerTotalRefund":
        { 
				"estimatedRefundAmount":
						{ 
						"value": 27.5
						"currency": USD,
						}
        },
    },
    { 
		"returnId": "5000080378",
		"currentType": MONEY_BACK,
		"state": RETURN_REQUESTED,
		"status": RETURN_REQUESTED,
		"creationInfo":
				{ 
				"creationDate":
						{ 
						"value": "2015-08-06T20:20:17.000Z"
						},
				"item":
						{ 
						"itemId": "190004540472",
						"transactionId": "8154428034",
						"returnQuantity": 1,
						},
				"reason": NO_LONGER_NEED_ITEM,
				"type": MONEY_BACK
				},
		"buyerLoginName": "buyer_544",
		"sellerLoginName": "seller_564",
		"buyerTotalRefund":
				{ 
				"estimatedRefundAmount":
						{ 
						"value": 34.75
						"currency": USD,
						}
				},
		"escalationInfo":
				{ 
				"buyerEscalationEligibilityInfo":
						{ 
						"eligible": true,
						"startTime":
								{ 
								"value": "2015-08-06T20:20:17.000Z"
								}
						"endTime":
								{ 
								"value": "2015-08-20T20:20:17.000Z"
								}
						},
				"sellerEscalationEligibilityInfo":
						{ 
						"eligible": true,
							 "startTime":
										{ 
										"value": "2015-08-06T20:20:17.000Z"
										}
								"endTime":
										{ 
										"value": "2015-08-20T20:20:17.000Z"
										}
								},
						}
				},
		"sellerAvailableOptions": [
				{ 
				"actionType": SELLER_APPROVE_REQUEST
				},
				{ 
				"actionType": SELLER_DECLINE_REQUEST
				},
				{ 
				"actionType": SELLER_SEND_MESSAGE
				}
			],
		"sellerResponseDue":
				{ 
				"activityDue": SELLER_APPROVE_REQUEST,
				"respondByDate":
						{ 
						"value": "2015-08-10T20:18:17.000Z"
						}
				},
		"sellerTotalRefund":
				{ 
				"estimatedRefundAmount":
						{ 
						"value": 34.75
						"currency": USD,
						}
				},
		},
		{ 
		"returnId": "5000080455",
		"currentType": REPLACEMENT,
		"state": REPLACEMENT_REQUESTED,
		"status": REPLACEMENT_REQUESTED,
		"creationInfo":
				{ 
				"creationDate":
						{ 
						"value": "2015-08-08T09:42:37.000Z"
						},
				"item":
						{ 
						"itemId": "190004540495",
						"transactionId": "8154429109",
						"returnQuantity": 1,
						},
				"reason": DEFECTIVE_ITEM,
				"type": REPLACEMENT
				},
		"buyerLoginName": "buyer_1028",
		"sellerLoginName": "seller_564",
		"escalationInfo":
				{ 
				"buyerEscalationEligibilityInfo":
						{ 
						"eligible": true,
						"startTime":
								{ 
								"value": "2015-08-08T09:42:37.000Z"
								}
						"endTime":
								{ 
								"value": "2015-08-22T09:42:37.000Z"
								}
						},
				"sellerEscalationEligibilityInfo":
						{ 
						"eligible": true,
						"startTime":
								{ 
								"value": "2015-08-08T09:42:37.000Z"
								}
						"endTime":
								{ 
								"value": "2015-08-22T09:42:37.000Z"
								}
						},
					}
				},
		"sellerAvailableOptions": [
				{ 
				"actionType": SELLER_APPROVE_REQUEST
				},
				{ 
				"actionType": SELLER_DECLINE_REQUEST
				},
				{ 
				"actionType": SELLER_SEND_MESSAGE
				}
			],
		"sellerResponseDue":
				{ 
				"activityDue": SELLER_APPROVE_REQUEST,
				"respondByDate":
						{ 
						"value": "2015-08-12T09:42:37.000Z"
						}
				},
		}
  ],
"paginationOutput":
    { 
    "limit": 100,
    "offset": 1,
    "totalEntries": 3,
    "totalPages": 1
    }
}



Change History

Change Date Description
1.0
2015-06-30
  • Call (added): New call.