--- title: Catalog API description: "The **Catalog API** allows users to search for and locate an eBay catalog product that is a direct match for the product that they wish to sell. Listing against an eBay catalog product helps insure that all listings (based off of that catalog product) have complete and accurate information. In addition to helping to create high-quality listings, another benefit to the seller of using catalog information to create listings is that much of the details of the listing will be prefilled, including the listing title, the listing description, the item specifics, and a stock image for the product (if available). Sellers will not have to enter item specifics themselves, and the overall listing process is a lot faster and easier." api_version: 1.0 api_name: catalog_api api_type: REST api_group: sell/catalog_api source_url: html: https://developer.ebay.com/develop/api/sell/catalog_api md: https://developer.ebay.com/develop/api/sell/catalog_api.md --- # Catalog API API The **Catalog API** allows users to search for and locate an eBay catalog product that is a direct match for the product that they wish to sell. Listing against an eBay catalog product helps insure that all listings (based off of that catalog product) have complete and accurate information. In addition to helping to create high-quality listings, another benefit to the seller of using catalog information to create listings is that much of the details of the listing will be prefilled, including the listing title, the listing description, the item specifics, and a stock image for the product (if available). Sellers will not have to enter item specifics themselves, and the overall listing process is a lot faster and easier. ## API Methods The following API methods are available: ### getProduct #### GET /product/{epid} **Description:** This method retrieves details of the catalog product identified by the eBay product identifier (ePID) specified in the request. These details include the product's title and description, aspects and their values, associated images, applicable category IDs, and any recognized identifiers that apply to the product. For a new listing, you can use the **search** method to identify candidate products on which to base the listing, then use the **getProduct** method to present the full details of those candidate products to the seller to make a a final selection. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) - This method uses the `X-EBAY-C-MARKETPLACE-ID` header to identify the seller's eBay marketplace. The Catalog API is supported in the following marketplaces: * Australia (EBAY\_AU) * Canada (EBAY\_CA) * Germany (EBAY\_DE) * Spain (EBAY\_ES) * France (EBAY\_FR) * Great Britain (EBAY\_GB) * Italy (EBAY\_IT) * US (EBAY\_US and EBAY\_MOTORS\_US) - **epid** (string) *required* - The eBay product identifier (ePID) of the product being requested. This value can be discovered by issuing the **search** method and examining the value of the **productSummaries.epid** field for the desired returned product summary. ### search #### GET /product_summary/search **Description:** This method searches for and retrieves summaries of one or more products in the eBay catalog that match the search criteria provided by a seller. The seller can use the summaries to select the product in the eBay catalog that corresponds to the item that the seller wants to offer for sale. When a corresponding product is found and adopted by the seller, eBay will use the product information to populate the item listing. The criteria supported by **search** include keywords, product categories, and category aspects. To see the full details of a selected product, use the **getProduct** call. In addition to product summaries, this method can also be used to identify _refinements_, which help you to better pinpoint the product you're looking for. A refinement consists of one or more _aspect_ values and a count of the number of times that each value has been used in previous eBay listings. An aspect is a property (e.g. color or size) of an eBay category, used by sellers to provide details about the items they're listing. The **refinement** container is returned when you include the **fieldGroups** query parameter in the request with a value of `ASPECT_REFINEMENTS` or `FULL`. **Example** A seller wants to find a product that is "gray" in color, but doesn't know what term the manufacturer uses for that color. It might be `Silver`, `Brushed Nickel`, `Pewter`, or even `Grey`. The returned **refinement** container identifies all aspects that have been used in past listings for products that match your search criteria, along with all of the values those aspects have taken, and the number of times each value was used. You can use this data to present the seller with a histogram of the values of each aspect. The seller can see which color values have been used in the past, and how frequently they have been used, and selects the most likely value or values for their product. You issue the **search** method again with those values in the **aspect\_filter** parameter to narrow down the collection of products returned by the call. Although all query parameters are optional, this method must include at least the **q** parameter, or the **category\_ids**, **gtin**, or **mpn** parameter with a valid value. If you provide more than one of these parameters, they will be combined with a logical AND to further refine the returned collection of matching products. **Note:** This method requires that certain special characters in the query parameters be percent-encoded:     `(space)` = `%20`       `,` = `%2C`       `:` = `%3A`       `[` = `%5B`       `]` = `%5D`       `{` = `%7B`       `|` = `%7C`       `}` = `%7D` This requirement applies to all query parameter values. However, for readability, method examples and samples in this documentation will not use the encoding. This method returns product summaries rather than the full details of the products. To retrieve the full details of a product, use the **getProduct** method with an ePID. **Parameters:** - **X-EBAY-C-MARKETPLACE-ID** (string) - This method also uses the `X-EBAY-C-MARKETPLACE-ID` header to identify the seller's eBay marketplace. The Catalog API is supported in the following marketplaces: * Australia (EBAY\_AU) * Canada (EBAY\_CA) * Germany (EBAY\_DE) * Spain (EBAY\_ES) * France (EBAY\_FR) * Great Britain (EBAY\_GB) * Italy (EBAY\_IT) * US (EBAY\_US and EBAY\_MOTORS\_US) - **aspect_filter** (string) - An eBay category and one or more aspects of that category, with the values that can be used to narrow down the collection of products returned by this call. Aspects are product attributes that can represent different types of information for different products. Every product has aspects, but different products have different sets of aspects. You can determine appropriate values for the aspects by first submitting this method without this parameter. It will return either the **productSummaries.aspects** container, the **refinement.aspectDistributions** container, or both, depending on the value of the **fieldgroups** parameter in the request. The **productSummaries.aspects** container provides the category aspects and their values that are associated with each returned product. The **refinement.aspectDistributions** container provides information about the distribution of values of the set of category aspects associated with the specified categories. In both cases sellers can select from among the returned aspects to use with this parameter. **Note:** You can also use the Taxonomy API's **getItemAspectsForCategory** method to retrieve detailed information about aspects and their values that are appropriate for your selected category. The syntax for the **aspect\_filter** parameter is as follows (on several lines for readability; **categoryId** is required): `aspect_filter=categoryId:_category_id_, _aspect1_:{_valueA_|_valueB_|...}, _aspect2_:{_valueC_|_valueD_|...},.` A matching product must be within the specified category, and it must have least one of the values identified for every specified aspect. **Note:** Aspect names and values are case sensitive. Here is an example of an **aspect\_filter** parameter in which `9355` is the category ID, `Color` is an aspect of that category, and `Black` and `White` are possible values of that aspect (on several lines for readability): `GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? aspect_filter=categoryId:9355,Color:{White|Black}` Here is the **aspect\_filter** with required URL encoding and a second aspect (on several lines for readability): `GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? aspect_filter=categoryId:9355,Color:%7BWhite%7CBlack%7D, Storage%20Capacity:%128GB%7C256GB%7D` **Note:** You cannot use the **aspect\_filter** parameter in the same method with either the **gtin** parameter or the **mpn** parameter. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/commerce/catalog/types/catal:AspectFilter - **category_ids** (string) - **Important:** Currently, only the first **category\_id** value is accepted. One or more comma-separated category identifiers for narrowing down the collection of products returned by this call. **Note:** This parameter requires a valid category ID value. You can use the Taxonomy API's **getCategorySuggestions** method to retrieve appropriate category IDs for your product based on keywords. The syntax for this parameter is as follows: `category_ids=_category_id1_,_category_id2_,.` Here is an example of a method with the **category\_ids** parameter: `GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? category_ids=178893` **Note:** Although all query parameters are optional, this method must include at least the **q** parameter, or the **category\_ids**, **gtin**, or **mpn** parameter with a valid value. If you provide only the **category\_ids** parameter, you cannot specify a top-level (L1) category. - **fieldgroups** (string) - The type of information to return in the response. **Important:** This parameter may not produce valid results if you also provide more than one value for the **category\_ids** parameter. It is recommended that you avoid using this combination. **Valid Values:** * `ASPECT_REFINEMENTS` — This returns the **refinement** container, which includes the category aspect and aspect value distributions that apply to the returned products. For example, if you searched for `Ford Mustang`, some of the category aspects might be **Model Year**, **Exterior Color**, **Vehicle Mileage**, and so on. **Note:** Aspects are category specific. * `FULL` — This returns all the refinement containers and all the matching products. This value overrides the other values, which will be ignored. * `MATCHING_PRODUCTS` — This returns summaries for all products that match the values you provide for the **q** and **category\_ids** parameters. This does not affect your use of the `ASPECT_REFINEMENTS` value, which you can use in the same call. Code so that your app gracefully handles any future changes to this list. **Default:** `MATCHING_PRODUCTS` - **gtin** (string) - A string consisting of one or more comma-separated Global Trade Item Numbers (GTINs) that identify products to search for. Currently the GTIN values can include EAN, ISBN, and UPC identifier types. **Note:** Although all query parameters are optional, this method must include at least the **q** parameter, or the **category\_ids**, **gtin**, or **mpn** parameter with a valid value. You cannot use the **gtin** parameter in the same method with either the **q** parameter or the **aspect\_filter** parameter. - **limit** (string) - The number of product summaries to return. This is the _result set_, a subset of the full collection of products that match the search or filter criteria of this call. **Maximum:** `200` **Default:** `50` - **mpn** (string) - A string consisting of one or more comma-separated Manufacturer Part Numbers (MPNs) that identify products to search for. This method will return all products that have one of the specified MPNs. MPNs are defined by manufacturers for their own products, and are therefore certain to be unique only within a given brand. However, many MPNs do turn out to be globally unique. **Note:** Although all query parameters are optional, this method must include at least the **q** parameter, or the **category\_ids**, **gtin**, or **mpn** parameter with a valid value. You cannot use the **mpn** parameter in the same method with either the **q** parameter or the **aspect\_filter** parameter. - **offset** (string) - This parameter is reserved for internal or future use. - **q** (string) - A string consisting of one or more keywords to use to search for products in the eBay catalog. **Note:** This method searches the following product record fields: **title**, **description**, **brand**, and **aspects.localizedName**, which do not include product IDs. Wildcard characters (e.g. `*`) are not allowed. The keywords are handled as follows: * If the keywords are separated by a comma (e.g. `iPhone,256GB`), the query returns products that have `iPhone` **AND** `256GB`. * If the keywords are separated by a space (e.g. `"iPhone ipad"` or `"iPhone, ipad"`), the query ignores any commas and returns products that have `iPhone` **OR** `iPad`. **Note:** Although all query parameters are optional, this method must include at least the **q** parameter, or the **category\_ids**, **gtin**, or **mpn** parameter with a valid value. You cannot use the **q** parameter in the same method with either the **gtin** parameter or the **mpn** parameter. ## Error Codes The following error codes may be returned by this API: ### REQUEST Errors #### 75007 - API_CATALOG **Description:** Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces}. #### 75010 - API_CATALOG **Description:** The specified EPID value {epid} was not found. #### 75011 - API_CATALOG **Description:** The specified EPID value {epid} no longer exists. Its new value is {newepid}. #### 75015 - API_CATALOG **Description:** Insufficient permissions to fulfill the request. #### 75016 - API_CATALOG **Description:** The specified EPID value {epid} is no longer available. #### 75001 - API_CATALOG **Description:** The call must have a valid 'q', or 'category\_ids' or 'gtin' or 'mpn' query parameter. #### 75004 - API_CATALOG **Description:** The 'limit' value should be between 1 and 200 (inclusive). #### 75006 - API_CATALOG **Description:** Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category. #### 75008 - API_CATALOG **Description:** The 'fieldgroups' value {fieldgroups} is invalid. The supported fieldgroups are: {supportedFieldgroups}. #### 75012 - API_CATALOG **Description:** The aspect\_filter format is invalid. For more information, see the API call reference documentation. #### 75013 - API_CATALOG **Description:** The 'aspect\_filter' query parameter must include a categoryId. For more information, see the API call reference documentation. #### 75014 - API_CATALOG **Description:** The categoryId in 'aspect\_filter' query parameter is invalid. For more information, see the API call reference documentation. #### 75017 - API_CATALOG **Description:** The specified GTIN value is invalid. #### 75018 - API_CATALOG **Description:** The call must be made with either 'q' or 'gtin/mpn'. #### 75019 - API_CATALOG **Description:** The call with 'gtin/mpn' cannot be made with aspect\_filter. ### APPLICATION Errors #### 75000 - API_CATALOG **Description:** There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. ## Rate Limits See [API Call Limits](https://developer.ebay.com/develop/get-started/api-call-limits) on the eBay Developer Program. ## Resources ### Documentation - [eBay Developer Program](https://developer.ebay.com/) - [API Documentation](https://developer.ebay.com/develop/api/) - [SDKs and Widgets](https://developer.ebay.com/develop/sdks-and-widgets) - [Developer Community Forum](https://community.ebay.com/t5/Developer-Groups/ct-p/developergroup) ### Tools - [API Explorer](https://developer.ebay.com/my/api_test_tool) - [GraphQL Explorer](https://developer.ebay.com/my/graphql_explorer) ### Support - [Developer Support](https://developer.ebay.com/support/) - [API Status](https://developer.ebay.com/support/api-status) - [Release Notes](https://developer.ebay.com/develop/api/release_notes/) --- *Generated on 2026-07-29T15:06:39.108Z*