Listing Recommendation API1.0.0
 

recommendationItemIds


Note: This initial version of the Listing Recommendation API is not available for testing in the Sandbox environment.

This call returns a list of the seller's items that have one or more listing recommendations of a specific type (listing recommendation type is used as an inclusive filter in the request). Because the list of items that are retrieved can be very large based on the seller's selling activity, this call is implemented with a pagination filter that allows the seller to retrieve one page of data (Item IDs) per call. Once the seller has retrieved all items that have listing recommendations of a certain type, they can then start running itemRecommendations calls using the corresponding Item ID and recommendationType values.

Back to top

recommendationItemIds Input

The seller's X-EBAY-GLOBAL-ID value is an optional HTTPS header for this call. Examples of this string value include 'EBAY-US' or 'EBAY-UK'. If this header is not specified, it defaults to 'EBAY-US'.

An example of a recommendationItemIds HTTPS request (with all possible parameters) is shown below. To learn more about an individual parameter and its possible values, click its name in the sample call (or scroll down to find it in the table).

See also Samples.

https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/recommendationItemIds?recommendationType=FnF&pageNumber=1&entriesPerPage=10


Parameter Type Occurrence Meaning
Call-Specific Query Parameters 
entriesPerPage int Optional The seller can specify the maximum number of Item IDs to display in a single "page" of data. This value, along with the number of Item IDs that match the input criteria, will determine the total pages (see pagination.totalPages) in the result set. This value defaults to '2500' if not specified.
Min: 1. Max: 5000. Default: 2500.
pageNumber int Required The seller must specify an integer value to control which page of data (Item IDs) is retrieved. The total number of result pages is determined by the total number of Item IDs (returned under the items container) matching the request criteria divided by the number of Item IDs to display per page of data (specified in the entriesPerPage field). If there are multiple pages of Item IDs to view, multiple recommendationItemIds calls can be made to view all Item IDs, and the pageNumber value can be incremented by 1 in each subsequent call.
recommendationType string Required The seller must specify one Listing Recommendation type in this field. Possible values include the following:
  • eTRS - use this filter to retrieve all listings that are not meeting one or more Top-Rated listing requirements;
  • ItemSpecifics - use this filter to retrieve all items that are missing recommended Item Specifics;
  • ProductIdentifier - use this filter to retrieve all listings that are missing the mandatory product identifier such as, Brand/MPN, UPS, ISBN or EAN;
  • Picture - use this filter to retrieve all listings that are not meeting eBay picture quality requirements;
  • Price - use this filter to retrieve all listings that are not optimally priced, or in the wrong listing format. This recommendation type is currently only supported on the US, UK, and DE sites;
  • Title - use this filter to retrieve all listings with Titles missing valuable keyword or Item Specifics, or listings with Titles containing keywords that are inaccurate, and which may lead to a bad buyer experience. This recommendation type is currently only supported on the US, UK, DE, and AU sites; and
  • FnF - use this filter to retrieve all listings that are missing fast handling for the item (same-day handling or handling time of 1 day) and/or missing at least one free shipping service option.

Back to top

recommendationItemIds Output

The XML sample response in the box below lists all parameters that might be returned in the response. To learn more about an individual parameter and its possible values, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<recommendationItemIdsResponse xmlns="http://www.ebay.com/marketplace/listing/v1/service">
  <!-- Call-Specific Output Fields -->
  <items>
    <itemId>string</itemId>
    <!-- ... more itemId fields possible here ... -->
  </items>
  <pagination>
    <entriesPerPage>int</entriesPerPage>
    <pageNumber>int</pageNumber>
    <totalEntries>int</totalEntries>
    <totalPages>int</totalPages>
  </pagination>
  <!-- (No Standard Output fields) -->
</recommendationItemIdsResponse>


Return Value Type Occurrence Meaning
Call-Specific Output Fields 
items container Always A container consisting of an array of itemId values that indicate which one of the seller's listings have one or more listing recommendations of the listing type specified in the recommendationType parameter in the request.
items.itemId string Always The unique identifier of a seller's listing that has one or more listing recommendations for the recommendation type specified in the recommendationType parameter in the request. Multiple itemId values can be returned under the items container. Specifically, an itemId value will be returned for each of the seller's listings that have one or more listing recommendations for the specified recommendation type..
pagination container Always Container consisting of fields that indicate the total number of pages and items that match the input criteria, the number of items per page, and the current page number being viewed.
pagination.entriesPerPage int Always This integer value indicates the maximum number of items that are set to be returned in a single "page" of data. This value, along with the number of items that match the input criteria, determines the total pages (see totalPages) in the result set.
pagination.pageNumber int Always This integer value indicates the "page" number of the results set. The total number of result pages is determined by the total number of items (see totalEntries) matching the request criteria divided by the number of items to display per page of data (see entriesPerPage). If there are multiple pages of items (see totalPages) to view, multiple recommendationItemIds requests can be made to view all items, and the pageNumber parameter value in the HTTPS request can be incremented by 1 in each subsequent call.
pagination.totalEntries int Always This value indicates the total number of items that exist based on the current input criteria. Once this value is known, the caller may want to considering tweaking the pageNumber and entriesPerPage parameter values in the HTTPS request and making another request.
pagination.totalPages int Always This value indicates the total number of result pages that exist based on the current input criteria, including the pageNumber and entriesPerPage parameter values in the HTTPS request. If totalPages is more than 1, multiple recommendationItemIds requests must be made to view all result pages, with the pageNumber parameter value being incremented by 1 in each subsequent HTTPS request.
(No Standard Output fields)

Back to top

recommendationItemIds Samples

Sample: Basic Call

This call retrieves the eBay Item IDs of listings that have one or more listing recommendations of a specific type.

Description

The following call retrieves all eBay Item IDs of listings that have 'Picture' listing recommendations. The pagination parameters are also set in the call.

Input

The recommendationIds HTTPS GET call will retrieve all of the seller's listings (identified by eBay Item ID) that have one or more 'Picture' listing recommendations. To retrieve the listings with 'Picture' listing recommendations, the seller passes in the value of 'Picture' in the recommendationType parameter. The pageNumber value is set to '1', which means that the first page of results will be returned, and the entriesPerPage value is '5', which means that as many as five Item IDs will appear on each page of results.

https://svcs.ebay.com/services/selling/listingrecommendation/v1/item/recommendationItemIds?recommendationType=Picture&pageNumber=1&entriesPerPage=5

Output

In the response below, five eBay Item IDs are returned. This indicates that these five items all have one or more 'Picture' listing recommendations. The next move for the seller might be to make an itemRecommendations call for each of these items.

The pagination container in the response consists of fields that indicate the total number of pages and items that match the input criteria, the number of items per page (which was set with the entriesPerPage parameter in the request), and the current page number being viewed (which was set with the pageNumber parameter in the request). As you can see from the values in the pagination container, there is actually a total of 16 items with 'Picture' listing recommendations and four pages of results. To view all four pages of items, the seller would have to make three more additional recommendationItemIds calls, while incrementing the pageNumber value by 1 for each subsequent call.

{
    "items": [
        280598875472,
        200875600012,
        280598904529,
        200875609522,
        290879280649
    ],
    "pagination": {
        "pageNumber": 1,
        "entriesPerPage": 5,
        "totalPages": 4,
        "totalEntries": 16
    }
}


recommendationItemIds Change History


Version Description
1.0.0
2015-07-10
  • (added) Added ProductIdentifier to recommendationType.
1.0.0
2013-04-12
  • (added) New call.