|Note: The Return Management API is enabled in production. It will return data for US sellers that are opted into eBay Return Center and have returns associated to them. The eBay Return Center pilot launched on July 10, 2012. The eBay Return Center full launch is scheduled for early August 2012. Please refer to http://pages.ebay.com/help/sell/return-process.html for more information on eBay returns and seller opt-in process.|
The Return Management API provides eligible eBay US sellers a programmatic way to retrieve and manage buyer returns created through Return Center. The Return Management API allows sellers to perform the following actions:
Refer to the Return Management API Call Reference for detailed information on each call, including input fields, output fields, and samples.
The getUserReturns call retrieves summary information of one or more buyer returns. This call can be used to retrieve returns created within the last 18 months. The next three sections describe the filters, sorting, and pagination options that are available with the getUserReturns call.
The getUserReturns call has filters available to restrict results to a date range, a specific return status, a specific listing, a specific order, a specific order line item, and/or a specific eBay member (on the other side of a return from the user making the call)
The creationDateRangeFilter container is used to restrict results to returns created within a specified date range. The maximum date range that can be used is 90 days.
The returnStatusFilter container is used to restrict results to returns that are in a specific state in the return flow. More than one return state can be specified in the returnStatusFilter container.
The itemFilter container is used to restrict results to a specific listing or to a specific order line item. For a multi-quantity, fixed price listing, more than one return may be retrieved.
The otherUserFilter container is used to retrieve returns for a specific user whom is on the other side of one or more returns.
If you expect the response payload of a getUserReturns call to be large, pagination can be used to control the number of returns returned per page of data. If there are multiple pages of returns to view, you can programmatically "scroll" through the pages by making subsequent calls, incrementing the paginationInput.pageNumber value each time until all pages have been viewed and/or handled.
See the getUserReturns call reference for more information on pagination.
There are sort options available in the getUserReturns request. The sortOrderType field allows the caller to choose between displaying results in descending or ascending order. The sortType field allows the caller to sort results based on the return filing date, the estimated amount of the return, the due date of the refund, or the buyer's user name.
If the sorting fields are not included in the getUserReturns request, the default value of sortOrderType is "Descending", and the default value of sortType is "FilingDate".
See the getUserReturns call reference for more information on sorting results.
A returns node is returned for each return that satisfies the input criteria. The following container/fields are always returned under a returns node:
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.
The following are some common errors that can occur when using filtering with the getUserReturns call:
The getReturnDetail call is used to retrieve detailed information on a return. The seller passes a return ID into the ReturnId.id field of the request. The Return ID value can be obtained with the getUserReturns call.
The two containers returned at the root level of the getReturnDetail response are ReturnSummary and ReturnDetail.
The ReturnSummary container consists of the following information:
The ReturnDetail container consists of the following information:
The getActivityOptions call is used by the seller to determine the next required action for the return. The seller passes a return ID into the ReturnId.id field of the request. The Return ID value can be obtained with the getUserReturns call.
The two possible activity options that are returned in the response are 'PROVIDE_SELLER_INFO' and 'ISSUE_REFUND'. If 'PROVIDE_SELLER_INFO' appears in the response, the seller can use the provideSellerInfo call to provide the buyer with a Return Merchandise Authorization number and/or an alternative return shipping address. If 'ISSUE_REFUND' appears in the response, the seller can use the issueRefund call to issue a refund to the buyer.
The seller can use the getReturnMetadata call to retrieve the following data:
If the seller wishes to retrieve all return metadata, no metadataEntryCode fields should be passed in the request.
The seller can use provideSellerInfo to provide a Return Merchandise Authorization number to the buyer (upon request from the buyer), or to provide an alternative return shipping address to the buyer.
The seller must also pass a return ID into the ReturnId.id field of the request. The Return ID value can be obtained with the getUserReturns call. eBay cannot verify the accuracy of the RMA number, so the accuracy of this number is the responsibility of the seller.
The returnAddress container is used by the seller to provide the buyer with an alternative return shipping address. If used in the call, this return shipping address will be used by the buyer instead of the primary return shipping address on file for the seller.
The seller will use issueRefund to issue a refund to the buyer.
The seller passes a return ID into the ReturnId.id field of the request to identify the return. The Return ID value can be obtained with the getUserReturns call.
The refundDetail container is used to provide the refund type and amount. An itemizedRefund container is required for each refund type, such as purchase price, original shipping, and restocking fee (if a Restocking Fee value was specified at listing time). The total refund amount is passed into the refundDetail.totalAmount field. The aggregate total of refund amounts passed in one or more itemizedRefund.amount fields should match the refundDetail.totalAmount value.
Optionally, the seller can provide a message regarding the refund using the comments field.
A RefundStatus enumeration value is returned in the response. 'SUCCESS' indicates that the refund to the buyer through PayPal was successful, and 'FAILED' indicates that the refund to the buyer through PayPal failed. 'PENDING' is for future use.
Back to top
Using the SetNotificationPreferences call of the Trading API, users can subscribe to the following platform notifications related to the activity of eBay Returns and the Return Management API.
For more information on these notifications and the Platform Notification process, see the Trading API Guide.
Back to top
Please refer to the API Call Limits page on the eBay Developer Network site for current default call limits and call limits for applications that have completed the Compatible Application Check, which is a free service that the eBay Developer Network provides to its members.
For more information about testing, refer to Testing Overview in the Making a Return Management API Call document.
Refer to the Call Reference for a list of calls in the Return Management API. The Call Reference includes the following information:
Back to top
You can get more information about the eBay Return Management API at these locations:
Back to top
Share tips or code samples related to this call or topic. Questions or observations are welcome, too.
eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.
This documentation and the API may only be used in accordance with the eBay Developer Network and API License Agreement.
© 2009–2011 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.