openapi: 3.0.0 info: 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. contact: name: eBay Inc, license: name: eBay API License Agreement url: https://go.developer.ebay.com/api-license-agreement version: v1_beta.5.0 servers: - url: https://api.ebay.com{basePath} description: Production variables: basePath: default: /commerce/catalog/v1_beta paths: /product/{epid}: get: tags: - product 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. operationId: getProduct parameters: - name: X-EBAY-C-MARKETPLACE-ID in: header description: >- This method also uses the X-EBAY-C-MARKETPLACE-ID header to identify the seller's eBay marketplace. It is required for all supported marketplaces, except EBAY_US, which is the default. required: false schema: type: string - name: epid in: path description: >- 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. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Product' '400': description: Bad Request x-response-codes: errors: '75007': domain: API_CATALOG category: REQUEST description: >- Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces}. '75010': domain: API_CATALOG category: REQUEST description: The specified EPID value {epid} was not found. '75011': domain: API_CATALOG category: REQUEST description: >- The specified EPID value {epid} no longer exists. Its new value is {newepid}. '75015': domain: API_CATALOG category: REQUEST description: Insufficient permissions to fulfill the request. '75016': domain: API_CATALOG category: REQUEST description: The specified EPID value {epid} is no longer available. '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error x-response-codes: errors: '75000': domain: API_CATALOG category: APPLICATION description: >- There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.inventory - https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly /product_summary/search: get: tags: - product_summary 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. operationId: search parameters: - name: X-EBAY-C-MARKETPLACE-ID in: header description: >- This method also uses the X-EBAY-C-MARKETPLACE-ID header to identify the seller's eBay marketplace. It is required for all supported marketplaces, except EBAY_US, which is the default. required: false schema: type: string - name: aspect_filter in: query description: >- 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 required: false schema: type: string - name: category_ids in: query description: >- 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.
required: false schema: type: string - name: fieldgroups in: query description: >- 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: Code so that your app gracefully handles any future changes to this list.

Default: MATCHING_PRODUCTS required: false schema: type: string - name: gtin in: query description: >- 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.
required: false schema: type: string - name: limit in: query description: >- 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 required: false schema: type: string - name: mpn in: query description: >- 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.
required: false schema: type: string - name: offset in: query description: This parameter is reserved for internal or future use. required: false schema: type: string - name: q in: query description: >- 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: 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.
required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ProductSearchResponse' '204': description: No Content '400': description: Bad Request x-response-codes: errors: '75001': domain: API_CATALOG category: REQUEST description: >- The call must have a valid 'q', or 'category_ids' or 'gtin' or 'mpn' query parameter. '75004': domain: API_CATALOG category: REQUEST description: The 'limit' value should be between 1 and 200 (inclusive). '75006': domain: API_CATALOG category: REQUEST description: >- Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category. '75007': domain: API_CATALOG category: REQUEST description: >- Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} . '75008': domain: API_CATALOG category: REQUEST description: >- The 'fieldgroups' value {fieldgroups} is invalid. The supported fieldgroups are: {supportedFieldgroups} '75012': domain: API_CATALOG category: REQUEST description: >- The aspect_filter format is invalid. For more information, see the API call reference documentation. '75013': domain: API_CATALOG category: REQUEST description: >- The 'aspect_filter' query parameter must include a categoryId. For more information, see the API call reference documentation. '75014': domain: API_CATALOG category: REQUEST description: >- The categoryId in 'aspect_filter' query parameter is invalid. For more information, see the API call reference documentation. '75015': domain: API_CATALOG category: REQUEST description: Insufficient permissions to fulfill the request. '75017': domain: API_CATALOG category: REQUEST description: The specified GTIN value is invalid. '75018': domain: API_CATALOG category: REQUEST description: The call must be made with either 'q' or 'gtin/mpn'. '75019': domain: API_CATALOG category: REQUEST description: The call with 'gtin/mpn' cannot be made with aspect_filter. '403': description: Forbidden '500': description: Internal Server Error x-response-codes: errors: '75000': domain: API_CATALOG category: APPLICATION description: >- There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.inventory - https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly components: schemas: Aspect: type: object properties: localizedName: type: string description: The localized name of this category aspect. localizedValues: type: array description: A list of the localized values of this category aspect. items: type: string description: This type contains the name and values of a category aspect. AspectDistribution: type: object properties: aspectValueDistributions: type: array description: >- Contains information about one or more values of the category aspect identified by localizedAspectName. items: $ref: '#/components/schemas/AspectValueDistribution' localizedAspectName: type: string description: >- The localized name of an aspect that is associated with the category identified by dominantCategoryId. description: >- This type contains information about one category aspect that is associated with a specified category. AspectValueDistribution: type: object properties: localizedAspectValue: type: string description: >- The localized value of the category aspect identified by refinement.aspectDistributions.localizedAspectName. matchCount: type: integer description: >- The number of times the value of localizedAspectValue has been used for eBay product listings. By comparing this quantity to the matchCount for other values of the same aspect, you can present a histogram of the values to sellers, who can use that information to select which aspect value is most appropriate for their product. You can then include the user-selected value in the the search call's aspect_filter parameter to refine your search. format: int32 refinementHref: type: string description: >- A HATEOAS reference that further refines the search with this particular localizedAspectValue. description: >- This type contains information about one value of a specified aspect. This value serves as a product refinement. Error: type: object properties: category: type: string description: Identifies the type of erro. domain: type: string description: >- Name for the primary system where the error occurred. This is relevant for application errors. errorId: type: integer description: A unique number to identify the error. format: int32 inputRefIds: type: array description: An array of request elements most closely associated to the error. items: type: string longMessage: type: string description: A more detailed explanation of the error. message: type: string description: >- Information on how to correct the problem, in the end user's terms and language where applicable. outputRefIds: type: array description: An array of request elements most closely associated to the error. items: type: string parameters: type: array description: >- An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned. items: $ref: '#/components/schemas/ErrorParameter' subdomain: type: string description: >- Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc. description: This type defines the fields that can be returned in an error. ErrorParameter: type: object properties: name: type: string description: The object of the error. value: type: string description: The value of the object. Image: type: object properties: height: type: integer description: The height of the image in pixels. format: int32 imageUrl: type: string description: The eBay Picture Services (EPS) URL of the image. width: type: integer description: The width of the image in pixels. format: int32 description: >- This type contains information about a product image stored in eBay Picture Services (EPS). Product: type: object properties: additionalImages: type: array description: >- Contains information about additional images associated with this product. For the primary image, see the image container. items: $ref: '#/components/schemas/Image' aspects: type: array description: >- Contains an array of the category aspects and their values that are associated with this product. items: $ref: '#/components/schemas/Aspect' brand: type: string description: The manufacturer's brand name for this product. description: type: string description: The rich description of this product, which might contain HTML. ean: type: array description: >- A list of all European Article Numbers (EANs) that identify this product. items: type: string epid: type: string description: The eBay product ID of this product. gtin: type: array description: >- A list of all GTINs that identify this product. Currently this can include EAN, ISBN, and UPC identifier types. items: type: string image: description: >- Contains information about the primary image of this product. For more images of this product, see the additionalImages container. $ref: '#/components/schemas/Image' isbn: type: array description: >- A list of all International Standard Book Numbers (ISBNs) that identify this product. items: type: string mpn: type: array description: >- A list of all MPN values that the manufacturer uses to identify this product. items: type: string otherApplicableCategoryIds: type: array description: >- A list of category IDs (other than the value of primaryCategoryId) for all the leaf categories to which this product might belong. items: type: string primaryCategoryId: type: string description: >- The identifier of the leaf category that eBay recommends using to list this product, based on previous listings of similar products. Products in the eBay catalog are not automatically associated with any particular category, but using an inappropriate category can make it difficult for prospective buyers to find the product. For other possible categories that might be used, see otherApplicableCategoryIds. productWebUrl: type: string description: The URL for this product's eBay product page. title: type: string description: The title of this product on eBay. upc: type: array description: A list of Universal Product Codes (UPCs) that identify this product. items: type: string version: type: string description: The current version number of this product record in the catalog. description: >- This type contains the full details of a specified product, including information about the product's identifiers, product images, aspects, and categories. ProductSearchResponse: type: object properties: href: type: string description: >- This field is reserved for internal or future use. limit: type: integer description: >- The number of product summaries returned in the response. This is the result set, a subset of the full collection of products that match the search or filter criteria of this call. If the limit query parameter was included in the request, this field will have the same value.

Default: 50 format: int32 next: type: string description: >- This field is reserved for internal or future use. offset: type: integer description: >- This field is reserved for internal or future use. format: int32 prev: type: string description: >- This field is reserved for internal or future use. productSummaries: type: array description: >- Returned if the fieldGroups query parameter was omitted from the request, or if it was included with a value of MATCHING_PRODUCTS or FULL. This container provides an array of product summaries in the current result set for products that match the combination of the q, category_ids, and aspect_filter parameters that were provided in the request. Each product summary includes information about the product's identifiers, product images, aspects, the product page URL, and the getProduct URL for retrieving the product details. items: $ref: '#/components/schemas/ProductSummary' refinement: description: >- Returned only if the fieldGroups query parameter was included in the request with a value of ASPECT_REFINEMENTS or FULL.

An aspect is a property of a category, used by sellers to provide details about the items they're listing. For example, the Cell Phones & Smartphones category (#9355) includes a Storage Capacity aspect.

This container provides information about the distribution of values of a set of category aspects. The category aspects are those associated with the category that eBay determines is most likely to cover the products that match the search criteria. $ref: '#/components/schemas/Refinement' total: type: integer description: >- This field is reserved for internal or future use. format: int32 description: >- This type contains the specifications for the collection of products that match the search or filter criteria of a search call. A maximum of 200 product summaries is returned (the result set), fewer if you include the limit query parameter in the request. ProductSummary: type: object properties: additionalImages: type: array description: >- Contains information about additional images associated with this product. For the primary image, see the image container. items: $ref: '#/components/schemas/Image' aspects: type: array description: >- Contains an array of the category aspects and their values that are associated with this product. items: $ref: '#/components/schemas/Aspect' brand: type: string description: The manufacturer's brand name for this product. ean: type: array description: >- A list of all European Article Numbers (EANs) that identify this product. items: type: string epid: type: string description: The eBay product ID of this product. gtin: type: array description: >- A list of all GTINs that identify this product. This includes all of the values returned in the ean, isbn, and upc fields. items: type: string image: description: >- Contains information about the primary image of this product. For more images of this product, see the additionalImages container. $ref: '#/components/schemas/Image' isbn: type: array description: >- A list of all International Standard Book Numbers (ISBNs) that identify this product. items: type: string mpn: type: array description: >- A list of all Manufacturer Product Number (MPN) values that the manufacturer uses to identify this product. items: type: string productHref: type: string description: >- The URI of the getProduct call request that retrieves this product's details. productWebUrl: type: string description: The URL for this product's eBay product page. title: type: string description: The title of this product on eBay. upc: type: array description: A list of Universal Product Codes (UPCs) that identify this product. items: type: string description: >- This type contains a summary of a specified product. The product summary includes information about the product's identifiers, product images, aspects, and the getProduct URL for retrieving the product details. Refinement: type: object properties: aspectDistributions: type: array description: >- Contains information about one or more aspects that are associated with the category identified by dominantCategoryId. items: $ref: '#/components/schemas/AspectDistribution' dominantCategoryId: type: string description: >- The ID of the category that eBay determines is most likely to cover the products matching the search criteria. description: >- This type identifies a product category and the aspects associated with that category. Each aspect distribution container returns the distribution of values that have been used for the aspect. securitySchemes: api_auth: type: oauth2 description: >- The security definitions for this API. Please check individual operations for applicable scopes. flows: authorizationCode: authorizationUrl: https://auth.ebay.com/oauth2/authorize tokenUrl: https://api.ebay.com/identity/v1/oauth2/token scopes: https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly: ' This scope would allow signed in user to read catalog data.' https://api.ebay.com/oauth/api_scope/sell.inventory: View and manage your inventory and offers