eBay Return Management APIVersion 1.1.0

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 Output Samples Change History

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.

Note: Effective September 26, 2025, both usernames and public user IDs will be accepted in this field. For more information, please refer to Data Handling Compliance.
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.



Input Output Samples Change History

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. Note: Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to Data Handling Compliance.
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. Note: Effective September 26, 2025, select developers will no longer receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to Data Handling Compliance.
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.



Input Output Samples Change History

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

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 specified date range are retrieved.

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月13日T15: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月12日T23:59:31.000Z</ns1:respondByDate>
 </ns1:responseDue>
 <ns1:creationDate>2012年01月06日T02: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月12日T23:59:49.000Z</ns1:respondByDate>
 </ns1:responseDue>
 <ns1:creationDate>2012年01月06日T03: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月12日T23:59:05.000Z</ns1:respondByDate>
 </ns1:responseDue>
 <ns1:creationDate>2012年01月06日T03: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月13日T15: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月12日T23:59:31.000Z</respondByDate>
 </responseDue>
 <creationDate>2012年01月06日T02: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月12日T23:59:49.000Z</respondByDate>
 </responseDue>
 <creationDate>2012年01月06日T03: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月12日T23:59:05.000Z</respondByDate>
 </responseDue>
 <creationDate>2012年01月06日T03:12:05.000Z</creationDate>
 </returns>
 <paginationOutput>
 <pageNumber>1</pageNumber>
 <entriesPerPage>3</entriesPerPage>
 <totalPages>1</totalPages>
 <totalEntries>3</totalEntries>
 </paginationOutput>
</getUserReturnsResponse>



Input Output Samples Change History

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.

AltStyle によって変換されたページ (->オリジナル) /