getUserReturns

Note: The Return Management API is no longer recommended. Instead, current users of the Return Management API should make plans to migrate to, and use the Return operations of the Post-Order API. New users interested is programmatically managing return requests, should also make plans to integrate with the Post-Order API. The Return Management API was developed to be used by sellers who had opted in to "Hassle-free Returns". Hassle-free Returns have been replaced by a new Returns Platform, where sellers fully or partially automate the processing of return requests through Return Automation Rules. The Return Management API does not support all features and logic of the new Returns Platform, and this API will be deprecated in the near future.

This call retrieves summary information for returns in which the user is involved as a buyer or seller. This call can be used to retrieve returns created within the last 18 months.

Note: Users of this call should start using the GET /post-order/v2/return/search call of the Post-Order API instead.

Request Details

Making a getUserReturns call with no input parameters will retrieve all returns in which the user is (or was) involved as a buyer or seller in the last 30 days. In addition to this basic call, there are also numerous filtering, sorting, and pagination options for a getUserReturns call, which are described below.

Using Filters

It is possible to use any and all filter types in one call, and boolean AND logic is used when retrieving results. Each filter types is described below:

Order Filter: the orderId filter can be used to retrieve returns filed against an order (can be more than one for multiple line item orders).
Item Filter: the itemFilter container can be used to retrieve returns filed against an item listing (can be more than one for multiple-quantity, fixed-price listings) or to retrieve a return filed against a specific order line item.
Return Status Filter: the ReturnStatusFilter container can be used to retrieve returns in specific state(s), such as ITEM_SHIPPED, CLOSED, MY_RESPONSE_DUE, and others.
Creation Date Filter: the creationDateRangeFilter container is used to set a date range. All returns created within this date range are retrieved. The maximum date range period is 90 days.
Other User Filter: the otherUserFilter container is used to retrieve returns for another eBay user acting in a buyer or seller role. If this filter type is used, all other filters will act in matching and retrieving returns for the specified user as opposed to the eBay user making the call.

Sorting Results

The two sorting fields are sortType and sortOrderType. sortType sets the primary entity to sort against, such as return filing date or estimated amount of return. If this field is not included in the request, the sort type defaults to "FilingDate". sortOrderType controls whether results are sorted in ascending or descending order. If this field is not included in the request, the sort order defaults to "Descending".

Using Pagination

The paginationInput container is used to control how many returns are included on one page of results, and if there are multiple pages of results, the pageNumber value is used to control which page of results is retrieved.

Pagination can be very helpful for managing large result sets. The seller can then use subsequent getUserReturns calls to retrieve results page by page by incrementing the pageNumber value in the request each time.

If paginationInput values are not used, up to 200 returns may be returned on one page. The entriesPerPage value defaults to 200, and the pageNumber value defaults to 1.

Working with the Response

A returns node is returned for each return that satisfies the input criteria. The following container/fields are always returned under a returns node:

creationDate: timestamp indicating when the return was opened by the buyer.
ReturnId.id: the unique identifier of the return. This value will be used in other Return Management API calls to identify the return to retrieve, to provide an Return Merchandise Authorization number, to issue a refund, to provide an alternative return address, or to get the next possible action to take on the return.
otherParty: this container identifies the eBay user on the other side of the return.
status: this field contains an enumeration value that indicates the current status of the return.
returnRequest: this container consists of details related to the item being returned, including the buyer's reason for returning the item.

The paginationOutput container is always returned regardless of whether the caller used the paginationInput container in the request. The paginationOutput container consists of values that indicate the total number of pages and returns that match the input criteria, the number of returns per page, and the current page number being viewed.

The responseDue container is returned if the buyer or seller has a pending response due in the return. The current status of the return dictates the type or response that is due.

Related Information

See also the reference documentation for this call:

getReturnDetail - This call can be used by a seller or buyer to retrieve detailed information about a specific return in which they are involved.

Input

See also Samples.

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

<?xml version="1.0" encoding="utf-8"?>
<getUserReturnsRequest xmlns="http://www.ebay.com/marketplace/returns/v1/services">
  <!-- Call-specific Input Fields -->
  <creationDateRangeFilter> DateRangeFilterType
    <fromDate> dateTime </fromDate>
    <toDate> dateTime </toDate>
  </creationDateRangeFilter>
  <itemFilter> ItemFilterType
    <itemId> string </itemId>
    <transactionId> string </transactionId>
  </itemFilter>
  <orderId> string </orderId>
  <otherUserFilter> UserFilterType
    <role> UserFilterRoleType </role>
    <userId> string </userId>
    <userLoginName> string </userLoginName>
  </otherUserFilter>
  <paginationInput> PaginationInput
    <entriesPerPage> int </entriesPerPage>
    <pageNumber> int </pageNumber>
  </paginationInput>
  <ReturnStatusFilter> ReturnStatusFilterType
    <ReturnStatus> ReturnStatusInputType </ReturnStatus>
    <!-- ... more ReturnStatus values allowed here ... -->
  </ReturnStatusFilter>
  <sortOrderType> ReturnSortOrderType </sortOrderType>
  <sortType> ReturnSortType </sortType>
</getUserReturnsRequest>

Argument	Type	Occurrence	Meaning

creationDateRangeFilter	DateRangeFilterType	Optional	Container used to restrict results to returns created within a specified date range. The specified date range is inclusive. The maximum date range that can be specified with this filter is 90 days. Returns with creation dates dating back more than 18 months cannot be retrieved. To retrieve returns for a period longer than 90 days, multiple getUserReturns calls must be made using this filter and specifying different date ranges in each subsequent call. If more than one filter type is used in one call, boolean AND logic is applied to the result set.
creationDateRangeFilter .fromDate	dateTime	Conditional	The starting date for the date range. The fromDate must be older than the toDate, and it cannot be set back more than 18 months in the past. This field is required if the dateRangeFilter container is used. If more than one filter type is used in one call, boolean AND logic is applied to the result set.
creationDateRangeFilter.toDate	dateTime	Optional	The ending date for the date range. The toDate must be more recent than the fromDate. This field is optional. If it is omitted, all returns created from the fromDate up to the present (system date) are returned, unless the range specified by the fromDate and the present date is greater than 90 days, in which case the toDate defaults to 90 days forward from the fromDate.
itemFilter	ItemFilterType	Optional	Container used to retrieve all returns related to a specific eBay listing, or to retrieve a return related to a specific order line item. Boolean OR logic is used if an eBay Item ID and Transaction ID are both specified. If more than one filter type is used in one call, boolean AND logic is applied to the result set.
itemFilter.itemId	string	Conditional	The unique identifier for an eBay listing. If specified, all returns filed against any of this listing's order line items are retrieved. An itemId value is required if the itemFilter container is used. If a transactionId value is used to identify a specific eBay order line item, that transactionId value must be associated with the itemId value or an error occurs. Max length: 19.
itemFilter.transactionId	string	Optional	The unique identifier for an eBay order line item. If a transactionId value is specified, any return filed against this order line item is retrieved. The transactionId value must be associated with the itemId value or an error occurs. Max length: 19.
orderId	string	Optional	A unique identifier of an eBay order. This field will accept an eBay-generated OrderID value or an OrderLineItemID value, which is a concatenation of ItemID and TransactionID with a hyphen separating these two IDs. If an orderId value is specified, any return filed against this order is retrieved. It is possible that multiple returns can be retrieved if the order has multiple line items, and the buyer filed a return against more than one of these order line items.
otherUserFilter	UserFilterType	Optional	Container used to retrieve all returns related to a specific eBay member, who is identified by role and either by user ID or login name or both. This other user must be on the other side of one or more returns from the calling user. If more than one filter type is used in one call, boolean AND logic is applied to the result set.
otherUserFilter.role	UserFilterRoleType	Conditional	The role (such as buyer or seller) of the other party involved in the return. This field is required if the otherUserFilter container is used. Applicable values: BUYER This value is specified in the otherUserFilter.role field to retrieve returns where the other user's role is buyer. BUYERORSELLER This value is specified in the otherUserFilter.role field to retrieve returns where the other user's role is buyer or seller. SELLER This value is specified in the otherUserFilter.role field to retrieve returns where the other user's role is seller.
otherUserFilter.userId	string	Conditional	The eBay user ID for the other party involved in the return. Either a userId or a userLoginName value must be specified in the otherUserFilter container.
otherUserFilter.userLoginName	string	Conditional	The eBay user login name for the other party involved in the return. Either a userId or a userLoginName value must be specified in the otherUserFilter container.
paginationInput	PaginationInput	Optional	Container used to control the pagination of the result set, including the number of returns to retrieve per page and the page number you want to retrieve in the output. Pagination is typically used when the result set is expected to be large. The caller can then use subsequent getUserReturns calls to retrieve results page by page by incrementing the pageNumber value in the request each time. The caller will know the total number of pages that need to be retrieved by looking at the paginationOutput.totalPages value in the response. If the paginationInput container is not used, all returns matching the filter criteria are retrieved and displayed on one "page" of the response.
paginationInput.entriesPerPage	int	Optional	This integer value is used to specify the maximum number of returns to display in a single "page" of data. This value, along with the number of returns that match the input criteria, will determine the total pages (see paginationOutput.totalPages) in the result set. This value defaults to '200' (the maximum allowed value) if not specified. Min: 1. Max: 200. Default: 200.
paginationInput.pageNumber	int	Optional	This integer value is used to specify the "page" of data to return in the call response. The total number of result pages is determined by the total number of returns (returned in paginationOutput.totalEntries) matching the request criteria divided by the number of returns to display per page of data (specified in entriesPerPage). This value defaults to '1' if not specified. If there are multiple pages of returns (see paginationOutput.totalPages) to view, multiple getUserReturns calls can be made to view all returns, and the pageNumber value can be incremented by 1 in each subsequent call. Min: 1. Max: 100. Default: 1.
ReturnStatusFilter	ReturnStatusFilterType	Optional	Container consisting of one or more ReturnStatus filters. If one or more ReturnStatus filters are used, results are restricted to returns in the specified states. If return status filtering is not used, returns in all states are retrieved. The ReturnStatusFilter container uses Boolean OR logic, which means that all returns matching the specified states are retrieved. If more than one filter type is used in one call, boolean AND logic is applied to the result set.
ReturnStatusFilter .ReturnStatus	ReturnStatusInputType	Conditional, repeatable: [1..*]	To retrieve returns in a specific state (such as open, closed, item shipped, etc.), pass in a ReturnStatusInputType value. At least one ReturnStatus field is required if the ReturnStatusFilter container is used, and multiple ReturnStatus values are allowed. Applicable values: CLOSED This value is passed into the ReturnStatusFilter.ReturnStatus field of the getUserReturns request to retrieve all closed returns. If CLOSED is used as a filter, returns in the following states (these values are indicated in the Returns.ReturnSummary.status field) are returned: CLOSED CS_CLOSED EXPIRED YOU_CONTACTED_CS_ABOUT_CLOSED_Return ITEM_SHIPPED This value is passed into the ReturnStatusFilter.ReturnStatus field of the getUserReturns request to retrieve all returns with the status of WAITING_DELIVERY. Return status values are indicated in the Returns.ReturnSummary.status field. MY_RESPONSE_DUE This value is passed into the ReturnStatusFilter.ReturnStatus field of the getUserReturns request to retrieve all returns in which the seller's response is due. The two applicable return status values returned in the Returns.ReturnSummary.status field are MY_PAYMENT_DUE and MY_RESPONSE_DUE. The MY_PAYMENT_DUE value indicates that the seller is expected to issue a refund to the buyer. The MY_RESPONSE_DUE value can indicate that the seller must provide an RMA number to the buyer, or the seller must contact eBay customer support. OTHER_PARTY_RESPONSE_DUE This value is passed into the ReturnStatusFilter.ReturnStatus field of the getUserReturns request to retrieve all returns in which the other party's response is due. The only applicable return status value returned in Returns.ReturnSummary.status field is OTHER_PARTY_RESPONSE_DUE. RETURN_STARTED This value is passed into the ReturnStatusFilter.ReturnStatus field of the getUserReturns request to retrieve all open returns. If RETURN_STARTED is used as a filter, returns in the following states (these values are indicated in the Returns.ReturnSummary.status field) are returned: MY_PAYMENT_DUE MY_RESPONSE_DUE OTHER_PARTY_CONTACTED_CS_AWAITING_RESPONSE OTHER_PARTY_RESPONSE_DUE PAID WAITING_DELIVERY YOU_CONTACTED_CS_AWAITING_RESPONSE
sortOrderType	ReturnSortOrderType	Optional	This field is used to sort returns in the response in descending or ascending order. So, if FilingDate is the sortType being used, and sortOrderType is set to Descending, returns are sorted in the response from the most recent filing date to the oldest filing date. Descending is the default value, so here is how the results will appear for each sortType: BuyerLoginName: Results are sorted based on name from Z to A EstimatedAmount: Results are sorted based on dollar amount from highest to lowest value FilingDate: Results are sorted based on filing date from most recent to oldest RefundDueDate: Results are sorted based on the date a refund is due to the seller from a date further in the future to a date less further in the future Default: Descending. Applicable values: Ascending This value is passed into the sortOrderType field of the getUserReturns call to display all retrieved returns in ascending order. See the ReturnSortType documentation to get an idea about how Ascending affects the four different sort types. Descending This value is passed into the sortOrderType field of the getUserReturns call to display all retrieved returns in descending order. See the ReturnSortType documentation to get an idea about how Descending affects the four different sort types. Descending is the default value and will be used if the sortOrderType field is not included in the getUserReturns request.
sortType	ReturnSortType	Optional	This field is used to sort returns in the response based on either return filing date, estimated refund amount, refund due date, or buyer login name. If this field is not used, returns are sorted by filing date. Default: FilingDate. Applicable values: BuyerLoginName If this value is specified, returns are sorted alphabetically based on the buyer's eBay login name. If sortOrder is set to Ascending, returns are sorted in alphabetical order according to eBay login name. If sortOrder is set to Descending, returns are sorted in reverse alphabetical order according to eBay login name. FilingDate is the default value, so returns will be sorted by filing date if a sortOrder value is not specified in the getUserReturns request. EstimatedAmount If this value is specified, returns are sorted based on the estimated amount of the return. If sortOrder is set to Descending, the highest value returns will appear first in the results set. If sortOrder is set to Ascending, the lowest value returns will appear first in the results set. FilingDate is the default value, so returns will be sorted by filing date if a sortOrder value is not specified in the getUserReturns request. FilingDate If this value is specified, returns are sorted based on the filing date of the return. If sortOrder is set to Descending, the most recent returns will appear first in the results set. If sortOrder is set to Ascending, the oldest returns will appear first in the results set. FilingDate is the default value, so returns will be sorted by filing date if a sortOrder value is not specified in the getUserReturns request. RefundDueDate If this value is specified, returns are sorted based on the refund due date. If sortOrder is set to Descending, returns with refund due dates the furthest in the future will appear first in the results set. If sortOrder is set to Ascending, returns with refund due dates the nearest in the future will appear first in the results set. FilingDate is the default value, so returns will be sorted by filing date if a sortOrder value is not specified in the getUserReturns request.

Output

See also Samples.

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<getUserReturnsResponse xmlns="http://www.ebay.com/marketplace/returns/v1/services">
  <!-- Call-specific Output Fields -->
  <paginationOutput> PaginationOutput
    <entriesPerPage> int </entriesPerPage>
    <pageNumber> int </pageNumber>
    <totalEntries> int </totalEntries>
    <totalPages> int </totalPages>
  </paginationOutput>
  <returns> ReturnSummaryType
    <creationDate> dateTime </creationDate>
    <lastModifiedDate> dateTime </lastModifiedDate>
    <otherParty> ReturnUserType
      <role> ReturnUserRoleType </role>
      <userId> string </userId>
    </otherParty>
    <responseDue> ReturnResponseDueType
      <party> ReturnUserType
        <role> ReturnUserRoleType </role>
        <userId> string </userId>
      </party>
      <respondByDate> dateTime </respondByDate>
    </responseDue>
    <ReturnId> ReturnIdType
      <id> string </id>
    </ReturnId>
    <returnRequest> ReturnRequestType
      <comments> string </comments>
      <returnItem> ReturnItemType
        <itemId> string </itemId>
        <returnQuantity> int </returnQuantity>
        <transactionId> string </transactionId>
      </returnItem>
      <!-- ... more returnItem nodes allowed here ... -->
      <returnReason> ReturnReasonType (EnumerationDetailType)
        <code> token </code>
      </returnReason>
    </returnRequest>
    <ReturnType> ReturnType </ReturnType>
    <status> ReturnStatusType </status>
  </returns>
  <!-- ... more returns nodes allowed here ... -->
  <!-- Standard Output Fields -->
  <ack> AckValue </ack>
  <errorMessage> ErrorMessage
    <error> ErrorData
      <category> ErrorCategory </category>
      <domain> string </domain>
      <errorId> long </errorId>
      <exceptionId> token </exceptionId>
      <message> string </message>
      <parameter name="string"> ErrorParameter (string) </parameter>
      <!-- ... more parameter values allowed here ... -->
      <severity> ErrorSeverity </severity>
      <subdomain> string </subdomain>
    </error>
    <!-- ... more error nodes allowed here ... -->
  </errorMessage>
  <timestamp> dateTime </timestamp>
  <version> string </version>
</getUserReturnsResponse>

Return Value	Type	Occurrence	Meaning

Call-specific Output Fields [Jump to standard fields]

paginationOutput	PaginationOutput	Always	Pagination container consisting of fields that indicate the total number of pages and returns that match the input criteria, the number of returns per page, and the current page number being viewed. The paginationOutput container is always returned even if pagination values are not specified in the request.
paginationOutput .entriesPerPage	int	Always	This integer value indicates the maximum number of returns to return in a single "page" of data. This value, along with the number of returns that match the input criteria, determines the total pages (see paginationOutput.totalPages) in the result set. Min: 1. Max: 100. Default: 1.
paginationOutput.pageNumber	int	Always	This integer value indicate the "page" number of the results set. The total number of result pages is determined by the total number of returns (returned in paginationOutput.totalEntries) matching the request criteria divided by the number of returns to display per page of data (indicated in paginationOutput.entriesPerPage). If there are multiple pages of returns (see paginationOutput.totalPages) to view, multiple getUserReturns calls can be made to view all returns, and the paginationInput.pageNumber value can be incremented by 1 in each subsequent call. Min: 1. Max: 200. Default: 1.
paginationOutput.totalEntries	int	Always	This value indicates the total number of returns that exist based on the current input criteria. Once this value is known, the caller may want to considering tweaking the paginationInput fields in the getUserReturns request and making another call.
paginationOutput.totalPages	int	Always	This value indicates the total number of result pages that exist based on the current input criteria, including the paginationInput fields. If totalPages is more than 1, multiple getUserReturns calls must be made to view all result pages, with the paginationInput.pageNumber value being incremented by 1 in each subsequent call.
returns	ReturnSummaryType	Always, repeatable: [1..*]	Container consisting of high-level information for each return matching the input criteria. This information includes the creation and modification dates for the return, the reason for the return, item information, response date, and the current status of the return.
returns.creationDate	dateTime	Always	This date indicates the date on which the return was created.
returns.lastModifiedDate	dateTime	Always	This date indicates the date on which the return was last modified.
returns.otherParty	ReturnUserType	Always	Container that identifies the other party involved in the return. The party is identified by eBay user ID and role (BUYER or SELLER).
returns.otherParty.role	ReturnUserRoleType	Always	The role (such as buyer or seller) of the party involved in the return. Applicable values: BUYER This value indicates that the user's role in the return is buyer. EBAY This value indicates that the user's role in the return is eBay. OTHER This value is reserved for future use. SELLER This value indicates that the user's role in the return is seller. SYSTEM This value indicates that the user's role in the return is system. Code so that your app gracefully handles any future changes to this list.
returns.otherParty.userId	string	Always	The eBay user ID for the party involved in the return.
returns.responseDue	ReturnResponseDueType	Conditionally	This container consists of the party whose response is due and the due date of that response. This container is only returned in the requests of the getUserReturns and getReturnDetail calls if a response is due from the seller or other party involved in the return.
returns.responseDue.party	ReturnUserType	Conditionally	Container that identifies the party whose response is due. The party is identified by eBay user ID and role (BUYER or SELLER).
returns.responseDue.party.role	ReturnUserRoleType	Always	The role (such as buyer or seller) of the party involved in the return. Applicable values: BUYER This value indicates that the user's role in the return is buyer. EBAY This value indicates that the user's role in the return is eBay. OTHER This value is reserved for future use. SELLER This value indicates that the user's role in the return is seller. SYSTEM This value indicates that the user's role in the return is system. Code so that your app gracefully handles any future changes to this list.
returns.responseDue.party .userId	string	Always	The eBay user ID for the party involved in the return.
returns.responseDue .respondByDate	dateTime	Conditionally	This date indicates the due date of the party's response.
returns.ReturnId	ReturnIdType	Always	Container consisting of the unique identifier for a return. Return ID values are returned in the ReturnId.id field of each ReturnSummary container returned in the getUserReturns and getReturnDetail calls.
returns.ReturnId.id	string	Always	This string value is the unique identifier for a return, and is returned in the responses of getUserReturns and getReturnDetail. For getReturnDetail, getActivityOptions, issueRefund, provideSellerInfo, provideTrackingInfo, and setItemAsReceived, a ReturnId value is a required input field. Max length: 38.
returns.returnRequest	ReturnRequestType	Always	Container consisting of details on the item being returned and the return reason.
returns.returnRequest.comments	string	Conditionally	This field contains any comments posted by the buyer upon opening the return. For a SNAD case, the buyer might state the discrepancies between the actual item received and the item described in the listing.
returns.returnRequest .returnItem	ReturnItemType	Always, repeatable: [1..*]	Container consisting of the eBay Item ID, the Transaction ID, and quantity of the item being returned to the seller. The returnItem container is returned in the getUserReturns and getReturnDetail calls.
returns.returnRequest .returnItem.itemId	string	Always	The unique identifier for an eBay listing. Max length: 19.
returns.returnRequest .returnItem.returnQuantity	int	Always	This value indicates the quantity of items to be returned. This value is usually '1' unless multiple identical items were purchased by the buyer. Min: 1.
returns.returnRequest .returnItem.transactionId	string	Always	The unique identifier for an eBay order line item.
returns.returnRequest .returnReason	ReturnReasonType (EnumerationDetailType)	Always	This value indicates the buyer's reason for returning an item. Possible values include I_DONT_WANT_IT (buyer remorse) and SNAD (item Significantly Not As Described).
returns.returnRequest .returnReason.code	token	Always	Unique identifier of the enumeration value.
returns.ReturnType	ReturnType	Always	This field indicates the return type. Through the Return Center, the buyer selects whether he/she wants to be refunded for the purchase or wants a replacement item. Applicable values: MONEY_BACK This value indicates that the buyer is returning/has returned the item for a refund. REPLACEMENT This value indicates that the buyer is requesting/has received a replacement item for the original item. UNKNOWN This value is only returned if client/user is running a version of the Return Management API that is out-of-date, and does not contain the latest values of ReturnType. Code so that your app gracefully handles any future changes to this list.
returns.status	ReturnStatusType	Always	This field indicates the current status of the return. This value will often give the seller a good idea about the next step to take in the return. Applicable values: See status. Code so that your app gracefully handles any future changes to this list.

Standard Output Fields

ack	AckValue	Always	A token representing the application-level acknowledgement code that indicates the response status, such as "Success". The AckValue enumeration type specifies the possible values for ack. Applicable values: Failure eBay encountered a fatal error during the processing of the request, causing the request to fail. When a serious application-level error occurs, the error is returned instead of the business data. PartialFailure eBay successfully processed the request, but one or more non-fatal errors occurred during the processing. Inspect the message details and resolve any problems before resubmitting the request. Success eBay successfully processed the request and the business data is returned in the response. Note that it is possible for a response to return Success, but still not contain the expected data in the result. Warning The request that triggered the error was processed successfully but with one or more warnings. Code so that your app gracefully handles any future changes to this list.
errorMessage	ErrorMessage	Conditionally	Information for an error or warning that occurred when eBay processed the request. This field is not returned if the ack value is Success.
errorMessage.error	ErrorData	Conditionally, repeatable: [0..*]	Details about a single error.
errorMessage.error.category	ErrorCategory	Conditionally	There are three categories of errors: request errors, application errors, and system errors. Applicable values: Application An error occurred due to a problem with the request, with the most likely source being the application sending the request. For example, the request is missing a required data element or it contains an invalid field. The problem must be corrected before the request can be resent. Inspect the error message to find the cause of the problem. If the problem is due to an application error, modify the application and resend the request. If the error is due to invalid data, the source of the data must be corrected before you resend the resend request to eBay. Request An error occurred due to a problem with the request, with the most likely source being missing or invalid data in the request. The problem must be corrected before the request can be retried. Inspect the error message to find the cause of the problem. If the problem is a result of end-user data, alert the end-user to the problem and provide the means for them to correct the problem. Once the problem is resolved, resend the request to eBay. System Indicates that an error has occurred on the eBay system side. For example, a database or server could be down. Inspect the error message to find the cause of the problem. If the problem is on the eBay side, an application can retry the request a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. Code so that your app gracefully handles any future changes to this list.
errorMessage.error.domain	string	Conditionally	Name of the domain in which the error occurred.
errorMessage.error.errorId	long	Conditionally	A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.
errorMessage.error.exceptionId	token	Conditionally	Unique identifier for an exception associated with an error.
errorMessage.error.message	string	Conditionally	A detailed description of the condition that caused the error.
errorMessage.error.parameter	ErrorParameter (string)	Conditionally, repeatable: [0..*]	Various warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error.
errorMessage.error.parameter [ attribute name ]	string	Conditionally	Various warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error.
errorMessage.error.severity	ErrorSeverity	Conditionally	Indicates whether the reported problem is fatal (an error) or is less severe (a warning). Review the error message details for information on the cause. If the request fails and the application is the source of the error (for example, a required element is missing), update the application before you retry the request. If the problem is due to incorrect user data, alert the end user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, resend the request to eBay. If the source of the problem is on eBay's side, you can retry the request a reasonable number of times (eBay recommends you try the request twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, you can resend the request in its original form. If a warning occurs, warning information is returned in addition to the business data. Normally, you do not need to resend the request (as the original request was successful). However, depending on the cause of the warning, you might need to contact the end user, or eBay, to effect a long term solution to the problem. Applicable values: Error eBay encountered a fatal error during the processing of the request, causing the request to fail. When eBay encounters an error, it returns error data instead of the requested business data. Inspect the error details and resolve the problem before resubmitting the request. Warning The request was successfully processed, but eBay encountered a non-fatal error during the processing that could affect the data returned. For example, eBay might have changed the value of an input field. In this Return, eBay returns a successful response, but it also returns a warning. For best results, requests should return without warnings. Inspect the warning details and resolve the problem before resubmitting the request. Code so that your app gracefully handles any future changes to this list.
errorMessage.error.subdomain	string	Conditionally	Name of the subdomain in which the error occurred.
timestamp	dateTime	Always	This value represents the date and time when eBay processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See Time Values in the eBay Features Guide for information about this time format and converting to and from the GMT time zone.
version	string	Always	The version of the response payload schema. Indicates the version of the schema that eBay used to process the request.

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

This call retrieves summary information for returns in which the user is involved as a buyer or seller. This call can be used to retrieve returns created within the last 18 months.

Description

The caller must be authenticated to make this call.

Input

This getUserReturns call sample is used by a seller named u********r. This seller uses the creationDateRangeFilter container, so all of this seller's returns created within the date range are retrieved. The fromDate and toDate values set the date range. In this specific sample, the seller is looking for all returns created from 11-26-2011 until 1-11-2012.

The seller also uses the paginationInput container to restrict the number of returns that appear on one page of results, noting that only one page can be returned per call. In this specific example, u********r wants to retrieve 50 returns per call (entriesPerPage=50), and wants the first page of results (pageNumber=1).

SOAP format. Also available is the XML equivalent.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://www.ebay.com/marketplace/returns/v1/services">
   <soap:Header/>
   <soap:Body>
      <ser:getUserReturnsRequest>
         <ser:RequesterCredentials>
             <ser:eBayAuthToken>A********3</ser:eBayAuthToken>
          </ser:RequesterCredentials>
         <ser:creationDateRangeFilter>
            <ser:fromDate>2011-11-26</ser:fromDate>
            <ser:toDate>2012-01-11</ser:toDate>
         </ser:creationDateRangeFilter>
          <ser:paginationInput>
            <ser:pageNumber>1</ser:pageNumber>
            <ser:entriesPerPage>50</ser:entriesPerPage>
         </ser:paginationInput>
      </ser:getUserReturnsRequest>
   </soap:Body>
</soap:Envelope>

Output

This specific call returns only three returns, which can be verified by looking at the paginationOutput.totalEntries value (at the end of the response). If you view the paginationOutput container, you'll notice that the entriesPerPage value changes to '3' to mirror the actual number of returns on the page, even though the paginationInput.entriesPerPage value was set to '50' in the request.

A returns container is returned for each return that matches the input criteria (in this call sample, all returns created from 11-26-2011 until 1-11-2012. The returns container is very similar to the ReturnSummary container returned in getReturnDetail and consists of data such as the following:

The return ID.
The role and user ID of the other party in the return. In this response, there are three unique buyers with returns filed against u********r.
The creation date of the return.
The current status of the return. The states in this response include ITEM_DELIVERED and READY_FOR_SHIPPING.
information on the item being returned, including the return reason. Return reasons in this response include DEFECTIVE_ITEM and ORDERED_ACCIDENTALLY
information on a response due from the seller or the buyer

SOAP format. Also available is the XML equivalent.

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Header/>
   <soapenv:Body>
      <ns1:getUserReturnsResponse xmlns:ns1="http://www.ebay.com/marketplace/returns/v1/services">
         <ns1:ack>Success</ns1:ack>
         <ns1:version>1.0.0</ns1:version>
         <ns1:timestamp>2012-01-13T15:29:30.596Z</ns1:timestamp>
         <ns1:returns>
            <ns1:ReturnId>
               <ns1:id>5********9</ns1:id>
            </ns1:ReturnId>
            <ns1:otherParty>
               <ns1:userId>e********0</ns1:userId>
               <ns1:role>BUYER</ns1:role>
            </ns1:otherParty>
            <ns1:returnRequest>
               <ns1:returnItem>
                 <ns1:itemId>1**********7</ns1:itemId>
                 <ns1:transactionId>2*********1</ns1:transactionId>
                 <ns1:returnQuantity>1</ns1:returnQuantity>
               </ns1:returnItem>
               <ns1:returnReason>
                 <ns1:code>9</ns1:code>
                 <ns1:description>DEFECTIVE_ITEM</ns1:description>
               </ns1:returnReason>
                <ns1:comments>test</ns1:comments>
            </ns1:returnRequest>
            <ns1:status>ITEM_DELIVERED</ns1:status>
            <ns1:responseDue>
               <ns1:party>
                  <ns1:userId>e********0</ns1:userId>
                  <ns1:role>BUYER</ns1:role>
               </ns1:party>
               <ns1:respondByDate>2012-01-12T23:59:31.000Z</ns1:respondByDate>
            </ns1:responseDue>
            <ns1:creationDate>2012-01-06T02:38:33.000Z</ns1:creationDate>
         </ns1:returns>
         <ns1:returns>
            <ns1:ReturnId>
               <ns1:id>5********1</ns1:id>
            </ns1:ReturnId>
            <ns1:otherParty>
               <ns1:userId>e********1</ns1:userId>
               <ns1:role>BUYER</ns1:role>
            </ns1:otherParty>
            <ns1:returnRequest>
               <ns1:returnItem>
                 <ns1:itemId>1**********8</ns1:itemId>
                 <ns1:transactionId>2*********1</ns1:transactionId>
                 <ns1:returnQuantity>1</ns1:returnQuantity>
               </ns1:returnItem>
               <ns1:returnReason>
                 <ns1:code>2</ns1:code>
                 <ns1:description>ORDERED_ACCIDENTALLY</ns1:description>
               </ns1:returnReason>
                <ns1:comments>test</ns1:comments>
            </ns1:returnRequest>
            <ns1:status>READY_FOR_SHIPPING</ns1:status>
            <ns1:responseDue>
               <ns1:party>
                  <ns1:userId>e********1</ns1:userId>
                  <ns1:role>BUYER</ns1:role>
               </ns1:party>
               <ns1:respondByDate>2012-01-12T23:59:49.000Z</ns1:respondByDate>
            </ns1:responseDue>
            <ns1:creationDate>2012-01-06T03:04:56.000Z</ns1:creationDate>
         </ns1:returns>
         <ns1:returns>
            <ns1:ReturnId>
               <ns1:id>5********4</ns1:id>
            </ns1:ReturnId>
            <ns1:otherParty>
               <ns1:userId>e********3</ns1:userId>
               <ns1:role>BUYER</ns1:role>
            </ns1:otherParty>
            <ns1:returnRequest>
               <returnItem>
                 <itemId>1**********6</itemId>
                 <transactionId>2*********1</transactionId>
                 <returnQuantity>1</returnQuantity>
               </returnItem>
               <returnReason>
                 <code>9</code>
                 <description>DEFECTIVE_ITEM</description>
               </returnReason>
                <comments>test</comments>
            </ns1:returnRequest>
            <ns1:status>READY_FOR_SHIPPING</ns1:status>
            <ns1:responseDue>
               <ns1:party>
                  <ns1:userId>e********3</ns1:userId>
                  <ns1:role>BUYER</ns1:role>
               </ns1:party>
               <ns1:respondByDate>2012-01-12T23:59:05.000Z</ns1:respondByDate>
            </ns1:responseDue>
            <ns1:creationDate>2012-01-06T03:12:05.000Z</ns1:creationDate>
         </ns1:returns>
         <ns1:paginationOutput>
            <ns1:pageNumber>1</ns1:pageNumber>
            <ns1:entriesPerPage>3</ns1:entriesPerPage>
            <ns1:totalPages>1</ns1:totalPages>
            <ns1:totalEntries>3</ns1:totalEntries>
         </ns1:paginationOutput>
      </ns1:getUserReturnsResponse>
   </soapenv:Body>
</soapenv:Envelope>

Here is the same output in XML format. Note that this does not include standard values.

XML format. Also available is the SOAP equivalent.

<?xml version="1.0" encoding="utf-8"?>
<getUserReturnsResponse xmlns:ns1="http://www.ebay.com/marketplace/returns/v1/services">
   <ack>Success</ack>
   <version>1.0.0</version>
   <timestamp>2012-01-13T15:29:30.596Z</timestamp>
   <returns>
      <ReturnId>
         <id>5********9</id>
      </ReturnId>
      <otherParty>
         <userId>e********0</userId>
         <role>BUYER</role>
      </otherParty>
      <returnRequest>
         <returnItem>
           <itemId>1**********7</itemId>
           <transactionId>2*********1</transactionId>
           <returnQuantity>1</returnQuantity>
         </returnItem>
         <returnReason>
           <code>9</code>
           <description>DEFECTIVE_ITEM</description>
         </returnReason>
         <comments>test</comments>
      </returnRequest>
      <status>ITEM_DELIVERED</status>
      <responseDue>
         <party>
            <userId>e********0</userId>
            <role>BUYER</role>
         </party>
         <respondByDate>2012-01-12T23:59:31.000Z</respondByDate>
      </responseDue>
      <creationDate>2012-01-06T02:38:33.000Z</creationDate>
   </returns>
   <returns>
      <ReturnId>
         <id>5********1</id>
      </ReturnId>
      <otherParty>
         <userId>e********1</userId>
         <role>BUYER</role>
      </otherParty>
      <returnRequest>
         <returnItem>
           <itemId>1**********8</itemId>
           <transactionId>2*********1</transactionId>
           <returnQuantity>1</returnQuantity>
         </returnItem>
         <returnReason>
           <code>2</code>
           <description>ORDERED_ACCIDENTALLY</description>
         </returnReason>
         <comments>test</comments>
      </returnRequest>
      <status>READY_FOR_SHIPPING</status>
      <responseDue>
         <party>
            <userId>e********1</userId>
            <role>BUYER</role>
         </party>
         <respondByDate>2012-01-12T23:59:49.000Z</respondByDate>
      </responseDue>
      <creationDate>2012-01-06T03:04:56.000Z</creationDate>
   </returns>
   <returns>
      <ReturnId>
         <id>5000000734</id>
      </ReturnId>
      <otherParty>
         <userId>e********3</userId>
         <role>BUYER</role>
      </otherParty>
      <returnRequest>
         <returnItem>
           <itemId>1**********6</itemId>
           <transactionId>2*********1</transactionId>
           <returnQuantity>1</returnQuantity>
         </returnItem>
         <returnReason>
           <code>9</code>
           <description>DEFECTIVE_ITEM</description>
         </returnReason>
         <comments>test</comments>
      </returnRequest>
      <status>READY_FOR_SHIPPING</status>
      <responseDue>
         <party>
            <userId>e********3</userId>
            <role>BUYER</role>
         </party>
         <respondByDate>2012-01-12T23:59:05.000Z</respondByDate>
      </responseDue>
      <creationDate>2012-01-06T03:12:05.000Z</creationDate>
   </returns>
   <paginationOutput>
      <pageNumber>1</pageNumber>
      <entriesPerPage>3</entriesPerPage>
      <totalPages>1</totalPages>
      <totalEntries>3</totalEntries>
   </paginationOutput>
</getUserReturnsResponse>

Change History

Change Date	Description
1.1.0 2014-01-14	returns.ReturnType (added): Indicates the return type as a refund ('Money_Back') or as a replacement item.
1.0.0 2012-04-23	(added) New call.