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?
  item_id=string&
  transaction_id=string&
  return_state=ReturnCountFilterEnum&
  offset=integer&
  limit=integer&
  sort=ReturnSortField&
  creation_date_range_from=string&
  creation_date_range_to=string&
  states=ReturnStateEnum

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' ands 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.
return_state string Optional Specify this query parameter if you want to retrieve return requests that are currently in a specific state or if you want to retrieve requests with a specific desired outcome (for example, returns for a refund or returns requesting a replacement item).

See ReturnCountFilterEnum for the list of values you can use in this parameter. If you don't include this parameter, all open return requests are returned.

Applicable values are from ReturnCountFilterEnum.
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 string --- Use this query parameter to specify one or more 'states' to retrieve with your call. See ReturnStateEnum for a complete list of values that can use in this parameter. Separate multiple state values with a comma.

Applicable values are from ReturnStateEnum.
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": string
    }
    /* 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": string,
        "type": string
        },
    "currentType": string,
    "dispositionRuleTriggered": [
        string
        /* More string 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
                }
            }
        },
    "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
    }
    /* 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 string 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 are from ReturnCountFilterEnum:See type.
Code so that your app gracefully handles any future changes to this list.
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 This field is for internal or future use.
members.buyerResponseDue
  .respondByDate.value
datetime Conditionally This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format:

Format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example: 2004-08-04T19:09:02.768Z

This field is always used for containers using the DateTime type.
members.buyerTotalRefund TotalRefundAmountType Conditionally This container shows the estimated and actual refund to the buyer. A refund to the buyer will generally be coming from seller.
members.buyerTotalRefund
  .actualRefundAmount
Amount Conditionally This container shows the actual refund amount that was issue to the buyer (if returned under the buyerTotalRefund container) or seller (if returned under the sellerTotalRefund container). This container is only returned if a refund has been issued.
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 This container shows the estimated refund amount that may be issued to the buyer (if returned under the buyerTotalRefund container) or seller (if returned under the sellerTotalRefund container).
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 This field is for internal or future use.
members.creationInfo
  .creationDate.value
datetime Conditionally This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format:

Format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example: 2004-08-04T19:09:02.768Z

This field is always used for containers using the DateTime type.
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 Conditionally This is the unique identifier of the listing. The itemId value and the transactionId values identify the order line item. This field is always returned with the item container.
members.creationInfo.item
  .returnQuantity
integer Conditionally 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. This field is always returned with the item container.
members.creationInfo.item
  .transactionId
string Conditionally This is the unique identifier of the transaction. The itemId value and the transactionId values identify the order line item. This field is always returned with the item container.
members.creationInfo.reason string Always This enumerated value indicates the buyer's reason for creating a return request or draft.

Applicable values are from ReturnReasonEnum:See reason.
Code so that your app gracefully handles any future changes to this list.
members.creationInfo.type string 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 are from ReturnTypeEnum:

CANCEL
This value is passed into the type field of the request when the buyer wants to cancel a return request (or draft).
MONEY_BACK
This value is passed into the type field of the request when the buyer is creating a return request (or draft), and wants a full refund after returning the item.
REPLACEMENT
This value is passed into the type field of the request when the buyer is creating a return request (or draft), but wants a replacement item instead of a refund.
UNKNOWN
This is the default value if the return type is not known.

Code so that your app gracefully handles any future changes to this list.
members.currentType string 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 are from ReturnTypeEnum:

CANCEL
This value is passed into the type field of the request when the buyer wants to cancel a return request (or draft).
MONEY_BACK
This value is passed into the type field of the request when the buyer is creating a return request (or draft), and wants a full refund after returning the item.
REPLACEMENT
This value is passed into the type field of the request when the buyer is creating a return request (or draft), but wants a replacement item instead of a refund.
UNKNOWN
This is the default value if the return type is not known.

Code so that your app gracefully handles any future changes to this list.
members
  .dispositionRuleTriggered
array of string Conditionally This enumerated value indicates the type of disposition rule triggered by the return request. More than one dispositionRuleTriggered field may be returned.

Applicable values are from DispositionRuleTemplateTypeEnum:

AUTO_REFUND_NO_SHIPBACK
Indicates the auto-refund with no return shipping disposition rule template will be used.
AUTO_ROUTE
Indicates the auto-route disposition rule template will be used.
OTHER
Indicates another disposition rule template will be used.
SEND_REPLACEMENT_NO_SHIPBACK
Indicates the replacement item with no return shipping disposition rule template will be used.

Code so that your app gracefully handles any future changes to this list.
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 This field is for internal or future use.
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .endTime.value
datetime Conditionally This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format:

Format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example: 2004-08-04T19:09:02.768Z

This field is always used for containers using the DateTime type.
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 This field is for internal or future use.
members.escalationInfo
  .buyerEscalationEligibilityInfo
  .startTime.value
datetime Conditionally This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format:

Format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example: 2004-08-04T19:09:02.768Z

This field is always used for containers using the DateTime type.
members.escalationInfo.caseId string Conditionally The unique identifier 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 This field is for internal or future use.
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .endTime.value
datetime Conditionally This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format:

Format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example: 2004-08-04T19:09:02.768Z

This field is always used for containers using the DateTime type.
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 This field is for internal or future use.
members.escalationInfo
  .sellerEscalationEligibilityInfo
  .startTime.value
datetime Conditionally This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format:

Format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example: 2004-08-04T19:09:02.768Z

This field is always used for containers using the DateTime type.
members.returnId string Conditionally The unique identifier 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 This field is for internal or future use.
members.sellerResponseDue
  .respondByDate.value
datetime Conditionally This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format:

Format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example: 2004-08-04T19:09:02.768Z

This field is always used for containers using the DateTime type.
members.sellerTotalRefund TotalRefundAmountType Conditionally This container shows the estimated and actual refund to the seller. A refund to the seller will generally be coming from eBay.
members.sellerTotalRefund
  .actualRefundAmount
Amount Conditionally This container shows the actual refund amount that was issue to the buyer (if returned under the buyerTotalRefund container) or seller (if returned under the sellerTotalRefund container). This container is only returned if a refund has been issued.
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 This container shows the estimated refund amount that may be issued to the buyer (if returned under the buyerTotalRefund container) or seller (if returned under the sellerTotalRefund container).
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
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.