Overview

The Inventory Discovery APIs allow users to discover eBay listings through query strings and other advanced search criteria and retrieve information about eBay listings. In addition, the Inventory Refresh APIs allow users to subscribe to push notifications that indicate when tracked listings have changed price, availability, or have been added or removed from a Promoted Listings campaign. 

API Use Cases

Discover and retrieve eBay items using the Browse API

Check product compatibility with a specified item

Downloading listings from a top–level (L1) category

Subscribe to push notifications to track listings

Discover and retrieve eBay items using the Browse API

The Browse API allows users to search for eBay items by various criteria, such as keywords, categories, or even images, as well as retrieve the details of a specific item or items.

Below is the basic flow used to discover and retrieve items using the Browse API: 

banner-image

Discovering items using the Browse API

Using the Browse API, you can search for and discover items by a variety of criteria, such as keywords, image ID (a Base64 string), eBay category ID, charity ID, eBay product ID (EPID), or GTIN (Global Trade Item Number), or a combination of these. 

The Browse API has the following methods to help buyers discover items based on their needs: 

  • Use search to search for eBay items using a variety of query parameters and retrieve a summary of the matching items. 
  • Use searchByImage to search for eBay items based on an image and retrieve summaries of the matching items. This image must be a base64 image, and can be retrieved using sites such as Image to Base64 Converter. 

The following query parameters are available to use for these methods to refine your item search:

Note: The searchByImage method only supports the following filter parameters: charity_ids, fieldgroups, category_ids, filter, and aspect_filter.

  • q: Search for items based on one or more keywords. 
  • autocorrect: Enables autocorrect for keywords. 
  • gtin: Search for items based on the Global Trade Item Number (GTIN) of the product.
  • charity_ids: Search for items that are associated with the specified charity. 
  • compatibilityFilter: Search for items in P&A categories that are compatible with the specified vehicle attributes. 
  • category_ids: Search for items in a specified category or categories.
  • filter: Search for items based on the criteria listed in the Buy API Field Filters table. 
  • aspectFilter: Search for items based on specific aspects of an item, such as color or size.
  • epid: Search for items based on the eBay product identifier of the product.

Additionally, you can use the fieldgroups parameter to control the fields and containers returned in the response. By default, this value is set to MATCHING_ITEMS, meaning only items that match the specified refinement criteria (shown above) will be returned. The following values are also available:

The sort parameter can be used to specify the criteria, in ascending order, for which returned items are sorted. Items can be sorted by price (price), distance from the buyer’s location (distance), the listing date (newlyListed), or by the date in which they are scheduled to end (endingSoonest).

The following pagination parameters are available to control the amount of data returned in the response payload:

  • limit: Specifies the number of items from the result set returned on a single page.

  • offset: Specifies the number of items to skip in the result set.

The following example shows a search for new drones between $300 and $500. If the call is successful, the first 5 drones (see the limit parameter) that match this criteria are returned: 

https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone&limit=5&filter=price:[300..800],priceCurrency:USD,conditions:{NEW}

Retrieving items using the Browse API

Once you have discovered an item or items using the search or searchByImage methods of the Browse API, you can use the getItem family of methods to retrieve details about a specific item. 

The getItem method can be used to retrieve the details of a specific item such as its description, price, category, aspects, condition, etc. The item to retrieve is specified by its RESTful item_id value. The format of this value is v1|{item_id}|{variation_id}. For single-variation listings, the {variation_id} value will be '0'. RESTful Item ID values can be retrieved using the search method of the Browse API detailed in the previous section. 

The fieldgroups query parameter can be used to control what is returned in the response. The following values can be used to control the response payload: 

  • PRODUCT: Adds the product container to the response.
  • COMPACT: Returns a select group of fields that allow the user to quickly check the item availability or if the item has been revised. See fieldgroups for more information on these fields.
  • ADDITIONAL_SELLER_DETAILS: Adds the userId field to the response. This value is the unique identifier of an eBay user across all eBay sites. This value does not change, even when a user changes their username.
  • CHARITY_DETAILS: Adds the charityTerms container to the response, if applicable.

Below are other methods applicable to retrieving items using the Browse API: 

  • Use getItemByItemGroup to retrieve the details about each variation within a multiple-variation listing.
  • Use getItemByLegacyId to retrieve the details of an item using the legacy item ID value (instead of the RESTful item ID value). 
  • Use getitems to retrieve the details of one or more items specified by their RESTful item ID values. Note that this is a restricted method that is only available to select partners.
Check product compatibility with a specified item 

In addition to searching for and retrieving items, the Browse API also has the capability to check if a specific Parts and Accessory item is compatible with a vehicle. For example, if a buyer wants to find new brake pads for their car, they can enter their vehicle property information (make, model, tire size, etc.) when using the search method and be returned with a list of possible compatible items. They can then use the checkCompatibility call to confirm that a product is compatible with their vehicle. 

To find valid attributes for a specific marketplace, use the compatibility methods of the Taxonomy API.

The following flow will allow you to check product compatibility for a specified item:

banner-image

  1. If needed, use search to find products that might be compatible with specific vehicle properties.

    1. The compatibility_filter query parameter can be used to search for items matching the keyword (specified by the q parameter) and the vehicle properties entered for this parameter. For example, if you set q=brakes and compatibility-filter=Year:2018;Make:BMW, only items with brakes, 2018, or BMW in the title, description, or aspects will be returned in the response.

    2. If one or more of the specified vehicle properties (in this case Year:2018 and Make:BMW) are compatible with a returned item in the response, the compatibilityProperties container will be returned for that item, listing the set of compatible vehicle properties for that item. If this container is not returned, none of the specified vehicle properties are compatible with the returned item.

    3. A value of EXACT will be returned in the compatibilityMatch field if the vehicle(s) under compatibilityProperties are verified to be fully compatible with the parts and accessories item. If only a subset of vehicle properties are returned in the compatibilityProperties container, the compatibilityMatch field will return with a value of POSSIBLE, meaning that the item might be compatible with the vehicle. When this value is returned, the checkCompatibility method can be used to verify if the item is compatible with the vehicle or not. See Step 2.

  2. Use checkCompatibility to check if a specified product is compatible with a specific vehicle.

    1. Pass in the item_id of the item you wish to check compatibility as a path parameter.

    2. Specify all the properties of the vehicle for which to check compatibility in the compatibilityProperties container.

    3. If the call is successful, product compatibility information for the item will be returned in the compatibilityStatus field. If the part is compatible with the vehicle, COMPATIBLEwill be returned. 

Downloading listings from a top-level (L1) category

Users can leverage the Feed APIs to mirror an eBay category by downloading feed files of the items in a specific L1 category on a specific marketplace.

Note: The list of available L1 categories can be retrieved using the getCategoryTree method of the Taxonomy APl.

eBay offers two Feed APIs: Feed Beta API and Feed API. Both of these APIs allow users to download listings from L1 categories, but have a few key differences discussed below:

  • The Feed Beta API allows users to download daily and weekly bootstrap feed files containing all items in a category. Users can also download hourly files of items that have changed in a category during that hour.
  • The Feed API allows users to retrieve information about the feed types and feed files they have access to, and then download those feed files.

Using the Feed Beta API to download listings

The Feed Beta API can be used to download TSV files containing items from a specific category on a specific marketplace. The following types of feed files are available for download using this API:

  • Weekly Item Bootstrap Feed: Downloads all fixed-priced items in a specific category.
  • Daily Item Feed: Downloads all fixed-priced items listed on a specific day, in a specific category.
  • Hourly Snapshot Feed: Downloads any active fixed-priced items that were updated within a specific hour, day, and category.

Using this API, users can download a Weekly Item Bootstrap Feed file containing all listings in a specified category on a given week, download a Daily Item Feed file to retrieve any items that have been listed on the days after the Weekly Bootstrap file was downloaded, and download a Hourly Snapshot Feed to retrieve items that have changed or been listed within the hour. Used concurrently, these three feed types allow users to keep a completely up-to-date mirror of any eBay category.

Below is the basic flow used to download items in a specific L1 category using the Feed Beta API: 

banner-text

The Feed Beta API methods used to retrieve and download items in L1 categories are discussed below: 

  • Use getItemFeed to download a feed file that contains all items from all the child categories in a specific category. One of the following feed_scope parameters must be specified when using this method:
    • NEWLY_LISTED: Returns the Daily Item Feed file containing all items that were listed on the specified day and in the specified category. If this scope is used, the date query parameter is required.
    • ALL_ACTIVE: Returns the Weekly Item Bootstrap Feed file containing all items in the specified category. Note that Weekly Item Bootstrap files return all active listings as of the date when the weekly feed file was last generated.
  • Use getItemGroupFeed to download a feed file that contains information about multiple-variation listings in a specific category. One of the following feed_scope parameters must be specified when using this method: 
    • NEWLY_LISTED: Returns a Daily Item Group Feed file that contains the item variation information for items returned in the Daily Item Feed file for a specific day, category, and marketplace. If this scope is used, the date query parameter is required.
    • ALL_ACTIVE: Returns a Weekly Item Group Bootstrap Feed file that contains all the item variation information associated with items returned in the Weekly Item Bootstrap Feed file for all items in a specific category. 
  • Use getItemSnapshotFeed to download an Hourly Snapshot Feed file containing the details of all items that have changed within the specified day and hour (specified by the snapshot_date query parameter) for a specific category. 

In addition to methods that allow users to download TSV files containing listings, this API also contains the getItemPriorityFeed method, which allows users to download a Daily Item Priority Feed file. This type of feed file allows users to track the changes in the status of their priority items, such as when they are added or removed from a Promoted Listings campaign. The category_id of the L1 category containing the items to be tracked is required as a query parameter for this method. 

Using the Feed API to download listings

The Feed API can be used to retrieve information about available feed types and feed files they have access to, and to download those files. 

The following flow will allow you to retrieve and download available feed files:

banner-text

  1. Use getAccess to retrieve the details of an application’s feed file access configuration, such as the marketplaces and categories for which the application can download feeds.

  2. Use getFeedTypes and getFeedType to retrieve additional information about each of these feed types, such as schema, supported marketplaces, and required authorization scopes. The following feed types are supported by the Feed API:

    • CURATED_ITEM_FEED: This feed type provides a curated collection of items, based on category and date, and returns a set of fields used to describe the curated items.

    • PRODUCT_FEED: This feed type provides a collection of items containing only a single offer per unique eBay Product Identifier (ePID) and item condition, and returns a set of fields used to describe the items.

    • PROMOTION: This feed type provides an hourly snapshot of live discounts and their currently associated items, and returns a set of fields used to describe the discounts.

    • CBT_ITEM_ALL_ACTIVE: This feed type is designed for the destination markets and provides a collection of items for international visibility. These feeds consist of inventory sourced from specific markets, which can be shipped to destination markets such as from Germany (DE) to Austria (AT). Note that the output for this feed file is AVRO, as opposed to TSV.

  3. Use getFiles or getFile to retrieve details about feed files available for download. Details about a feed file, such as the date it was generated, its feed type, supported marketplaces, etc, will be returned for each file. The fileId value for each file will also be returned, which will be needed to download the file.

  4. Use downloadFile to download a GZIP file of a specified feed file using its fileId.

Subscribe to push notifications to track listings

Integrating with eBay's Notification API allows third-party platforms to subscribe to and receive various types of notifications that eBay will send to the user's destination endpoint. The following notification topics are available to help users track listings that have changed price or availability, or that have been added or removed from a Promoted Listings Campaign: 

Note: Currently, these topics are available for eBay Partner Network (ePN) partners in all marketplaces except for the following: CA, AU, HK, SG, MY, and PH.

  • Item Availability: This notification is sent to a developer when a fixed price item's availability type changes.
  • Item Price Revision: This notification is sent to a developer when a fixed price item's price changes.
  • Priority Listing Revision: This notification is sent to sellers when their Promoted Listing has been revised.

The following flow will allow you to start receiving these notifications to your configured endpoint:

  1. Use createDestination to set up an endpoint for receiving notifications from eBay. This endpoint is required for handling incoming notification data securely.
  2. Use getTopics to retrieve the full list of notification topics available. Pay attention to any OAuth scopes in the authorizationScopes array. Some topics require special scopes; if you lack the necessary scope(s), you cannot subscribe to that topic. Also, note the topicId values as these are required to subscribe to those topics.
  3. Use createSubscription to subscribe to a topic. Specify the topicId value for the topic, the endpoint that will receive these notifications, and set the status value to ENABLED.
  4. For every notification sent to the endpoint, extract the Base64-encoded X-EBAY-SIGNATURE header included in the eBay notification. Pass this value as a path parameter in the getPublicKey method. The key value returned in the response is used to validate the eBay push notification message payload.
  5. Take any necessary action based on the notification.

Code samples

Search for items by keyword

curl -X GET "https://api.ebay.com/buy/browse/v1/item_summary/search?q=drone"
-H "Authorization:Bearer OAUTH_token"
-H "X-EBAY-C-MARKETPLACE-ID:EBAY_US"

Retrieve supported topics

curl -X GET "https://api.ebay.com/commerce/notification/v1/topic"
-H "Authorization:Bearer OAUTH_token"

Error Handling

  • When retrieving an item using the Browse API, you may get an error message stating the specified item ID is not valid. This may be because there are differences between how legacy APIs and RESTful APIs define the identifier of an "item" and what the item ID represents. If you wish to use an eBay legacy item identifier when using the Browse API, you can use the getItemByLegacyId method to retrieve items. For details, see the Legacy API compatibility in the Buying Integration Guide.
  • If you are receiving an error stating the feed file does not exist or may have expired when attempting to download a feed file when using the Feed API, use getFeedType to check the marketplaceIds and lookBack value associated with the feed type you are attempting to download. 
  • If you are receiving an ‘insufficient permissions’ error when attempting to download a feed file using the Feed API, use getFeedType to check the authorizationScopes associated with the feed type. Each feed type has an OAuth authorization scope required to grant access to the feed type.
  • While the Feed Beta API is available for use in the sandbox environment, it is restricted to certain categories. In addition, bootstrap feeds are not supported in the sandbox environment.. See Sandbox limitations and support for more information.
  • If you receive an error while attempting to subscribe to the Item Availability or Item Price Revision notifications, check to make sure you are supplying the required scope. The following scope is required for these two notifications: https://api.ebay.com/oauth/api_scope/buy.item.stream

Best Practices

  • Although not required, it is strongly recommended that you use the X-EBAY-C-ENDUSERCTX header with the contextualLocationattribute when making a call to Browse API. This header enables users to specify location information, increasing the accuracy of the estimated delivery window information and is required for calculated shipping information. This header can also be used to provide ePN affiliate information. 
  • Using the Browse API, sellers are able to use data returned in the aspect refinement container (aspectDistributions) to create histograms that enable shoppers to drill down in each refinement and narrow the search results.
  • Instead of retrieving large feed files in "chunks" through the various Feed API and Feed Beta API methods, you can use the open source Feed V1 SDK (or Feed SDK for Feed Beta API) to retrieve the feed file. These SDKs download and combine the feed files into a single file when needed, and unzip the entire feed file. They also let you specify field filters to curate the items in the file.
  • When using the Feed Beta API, it is recommended that you download the Bootstrap files on Thursdays. This is because while Bootstrap files are generated every Tuesday, with the files generally being available on Wednesday, the exact time the file is available can vary.
  • To keep downloaded listings up to date when mirroring a category with the Feed Beta API, it is recommended you download Daily Item Feed files for each day between the date you downloaded a Bootstrap file and the date of the Last-Modified response header of the file. For example, if you download a Bootstrap file on Friday, and the Last-Modified date of the file says Sunday, you should use getItemFeed with feed_scope=NEWLY_LISTED for each previous day (Monday through Thursday) to download any newly-listed items.