--- swagger: "2.0" info: 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." version: "v1_beta.5.0" title: "Catalog API" contact: name: "eBay Inc," license: name: "eBay API License Agreement" url: "https://go.developer.ebay.com/api-license-agreement" host: "api.ebay.com" basePath: "/commerce/catalog/v1_beta" schemes: - "https" 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" produces: - "application/json" 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\ \ marketplaces except EBAY_US, which is the default. Note: This method\ \ is limited to EBAY_US, EBAY_AU, EBAY_CA,\ \ and EBAY_GB values." required: false type: "string" - name: "epid" in: "path" description: "The 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 type: "string" responses: 200: description: "OK" schema: $ref: "#/definitions/Product" 400: description: "Bad Request" x-response-codes: errors: 75011: domain: "API_CATALOG" category: "REQUEST" description: "The specified EPID value {epid} no longer exists. Its\ \ new value is {newepid}." 75010: domain: "API_CATALOG" category: "REQUEST" description: "The specified EPID value {epid} was not found." 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." 75007: domain: "API_CATALOG" category: "REQUEST" description: "Currently, the {marketplaceId} marketplace is not supported.\ \ The supported Marketplaces are: {allowedMarketplaces}." 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." 403: description: "Forbidden" 404: description: "Not Found" security: - Authorization Code: - "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" produces: - "application/json" 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\ \ marketplaces except EBAY_US, which is the default. Note: This method\ \ is limited to EBAY_US, EBAY_AU, EBAY_CA,\ \ and EBAY_GB values." required: false 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 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: br />
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 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:
    \ \
  • 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" required: false 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 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 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 type: "string" - name: "offset" in: "query" description: "This parameter is reserved for internal or future use." required: false 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:\ \
  • 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.
" required: false type: "string" responses: 200: description: "Success" schema: $ref: "#/definitions/ProductSearchResponse" 400: description: "Bad Request" x-response-codes: errors: 75008: domain: "API_CATALOG" category: "REQUEST" description: "The 'fieldgroups' value {fieldgroups} is invalid. The\ \ supported fieldgroups are: {supportedFieldgroups}" 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." 75012: domain: "API_CATALOG" category: "REQUEST" description: "The aspect_filter format is invalid. For more information,\ \ see the API call reference documentation." 75015: domain: "API_CATALOG" category: "REQUEST" description: "Insufficient permissions to fulfill the request." 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." 75001: domain: "API_CATALOG" category: "REQUEST" description: "The call must have a valid 'q', or 'category_ids' or\ \ 'gtin' or 'mpn' query parameter." 75017: domain: "API_CATALOG" category: "REQUEST" description: "The specified GTIN value is invalid." 75019: domain: "API_CATALOG" category: "REQUEST" description: "The call with 'gtin/mpn' cannot be made with aspect_filter." 75018: domain: "API_CATALOG" category: "REQUEST" description: "The call must be made with either 'q' or 'gtin/mpn'." 75004: domain: "API_CATALOG" category: "REQUEST" description: "The 'limit' value should be between 1 and 200 (inclusive)." 75007: domain: "API_CATALOG" category: "REQUEST" description: "Currently, the {marketplaceId} marketplace is not supported.\ \ The supported Marketplaces are: {allowedMarketplaces} ." 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." 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." 204: description: "No Content" 403: description: "Forbidden" security: - Authorization Code: - "https://api.ebay.com/oauth/api_scope/sell.inventory" - "https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly" securityDefinitions: Authorization Code: description: "The security definitions for this API. Please check individual operations\ \ for applicable scopes." type: "oauth2" authorizationUrl: "https://auth.ebay.com/oauth2/authorize" tokenUrl: "https://api.ebay.com/identity/v1/oauth2/token" flow: "accessCode" 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" definitions: 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: "#/definitions/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." 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." Image: type: "object" properties: height: type: "integer" description: "The height of the image in pixels." imageUrl: type: "string" description: "The eBay Picture Services (EPS) URL of the image." width: type: "integer" description: "The width of the image in pixels." 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: "#/definitions/Image" aspects: type: "array" description: "Contains an array of the category aspects and their values that\ \ are associated with this product." items: $ref: "#/definitions/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: $ref: "#/definitions/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" 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. " prev: type: "string" description: "This field is reserved for internal or future use. !-- Not\ \ returned if the currently returned result set is the first set of\ \ product records from the current collection of matching products. This\ \ field contains the search call URI for the previous result set.\ \ For example, the following URI returns products 21 thru 30 from the collection\ \ of products:

path/product_summary/search?limit=10&offset=20\ \

Note: This feature\ \ employs a zero-based list, where the first product in the list has an\ \ offset of 0. >" 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: "#/definitions/ProductSummary" refinement: $ref: "#/definitions/Refinement" total: type: "integer" description: "This field is reserved for internal or future use.