--- openapi: "3.0.0" info: title: "Taxonomy API" description: "Use the Taxonomy API to discover the most appropriate eBay categories\ \ under which sellers can offer inventory items for sale, and the most likely\ \ categories under which buyers can browse or search for items to purchase. In\ \ addition, the Taxonomy API provides metadata about the required and recommended\ \ category aspects to include in listings, and also has two operations to retrieve\ \ parts compatibility information." contact: name: "eBay Inc," license: name: "eBay API License Agreement" url: "https://developer.ebay.com/join/api-license-agreement" version: "v1.1.1" servers: - url: "https://api.ebay.com{basePath}" description: "Production" variables: basePath: default: "/commerce/taxonomy/v1" paths: /category_tree/{category_tree_id}/fetch_item_aspects: get: tags: - "category_tree" summary: "Get Aspects for All Leaf Categories in a Marketplace" description: "This method returns a complete list of aspects for all of the\ \ leaf categories that belong to an eBay marketplace. The eBay marketplace\ \ is specified through the category_tree_id URI parameter.

Note: A successful call returns a\ \ payload as a gzipped JSON file sent as a binary file using the content-type:application/octet-stream\ \ in the response. This file may be large (over 100 MB, compressed). Extract\ \ the JSON file from the compressed file with a utility that handles .gz or\ \ .gzip. The open source Taxonomy SDK can be used to compare the aspect metadata\ \ that is returned in this response. The Taxonomy SDK uses this call\ \ to surface changes (new, modified, and removed entities) between an updated\ \ version of a bulk downloaded file relative to a previous version." operationId: "fetchItemAspects" parameters: - name: "category_tree_id" in: "path" description: "The unique identifier of the eBay category tree. The category\ \ tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId\ \ method." required: true schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/GetCategoriesAspectResponse" "400": description: "Bad Request" x-response-codes: errors: 62004: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category tree ID was not found." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "404": description: "Not found" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" - "https://api.ebay.com/oauth/api_scope/metadata.insights" /get_default_category_tree_id: get: tags: - "category_tree" summary: "Get a Default Category Tree ID" description: "A given eBay marketplace might use multiple category trees, but\ \ one of those trees is considered to be the default for that marketplace.\ \ This call retrieves a reference to the default category tree associated\ \ with the specified eBay marketplace ID. The response includes only the tree's\ \ unique identifier and version, which you can use to retrieve more details\ \ about the tree, its structure, and its individual category nodes." operationId: "getDefaultCategoryTreeId" parameters: - name: "marketplace_id" in: "query" description: "The unique identifier of the eBay marketplace for which the\ \ category tree ID is requested. For a list of supported marketplace IDs,\ \ see Marketplaces with Default Category Trees." required: true schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/BaseCategoryTree" "400": description: "Bad Request" x-response-codes: errors: 62002: domain: "API_TAXONOMY" category: "REQUEST" description: "Missing marketplace ID." 62003: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified marketplace ID was not found." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "204": description: "No content" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" /category_tree/{category_tree_id}: get: tags: - "category_tree" summary: "Get a Category Tree" description: "This method retrieves the complete category tree that is identified\ \ by the category_tree_id parameter. The value of category_tree_id\ \ was returned by the getDefaultCategoryTreeId method in the categoryTreeId\ \ field. The response contains details of all nodes of the specified eBay\ \ category tree, as well as the eBay marketplaces that use this category tree.

Note: This method can return a very\ \ large payload, so gzip compression is supported. To enable gzip compression,\ \ include the Accept-Encoding header and set its value to gzip\ \ as shown below:

  Accept-Encoding: gzip" operationId: "getCategoryTree" parameters: - name: "category_tree_id" in: "path" description: "The unique identifier of the eBay category tree. The category\ \ tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId\ \ method." required: true schema: type: "string" - name: "Accept-Encoding" in: "header" description: "This header indicates the compression-encoding algorithms the\ \ client accepts for the response. This value should be set to gzip.\ \

For more information, refer to HTTP request headers." required: false schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/CategoryTree" "400": description: "Bad Request" x-response-codes: errors: 62004: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category tree ID was not found." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "404": description: "Not Found" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" /category_tree/{category_tree_id}/get_category_subtree: get: tags: - "category_tree" summary: "Get a Category Subtree" description: "This call retrieves the details of all nodes of the category tree\ \ hierarchy (the subtree) below a specified category of a category tree. You\ \ identify the tree using the category_tree_id parameter, which was\ \ returned by the getDefaultCategoryTreeId call in the categoryTreeId\ \ field.

Note: This method\ \ can return a very large payload, so gzip compression is supported. To enable\ \ gzip compression, include the Accept-Encoding header and set\ \ its value to gzip as shown below:

  Accept-Encoding:\ \ gzip" operationId: "getCategorySubtree" parameters: - name: "category_id" in: "query" description: "The unique identifier of the category at the top of the subtree\ \ being requested. Metadata on this category and all its descendant categories\ \ are retrieved.

Note:\ \ If the category_id submitted identifies a leaf node of the tree,\ \ the call response will contain information about only that leaf node,\ \ which is a valid subtree. " required: true schema: type: "string" - name: "category_tree_id" in: "path" description: "The unique identifier of the eBay category tree. The category\ \ tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId\ \ method." required: true schema: type: "string" - name: "Accept-Encoding" in: "header" description: "This header indicates the compression-encoding algorithms the\ \ client accepts for the response. This value should be set to gzip.\ \

For more information, refer to HTTP request headers." required: false schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/CategorySubtree" "400": description: "Bad Request" x-response-codes: errors: 62004: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category tree ID was not found." 62005: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category ID does not belong to the specified\ \ category tree." 62006: domain: "API_TAXONOMY" category: "REQUEST" description: "Missing category ID." 62008: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category ID is the root for the category\ \ tree. Please use {categoryTreeHref} to retrieve the\ \ entire tree." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "404": description: "Not Found" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" /category_tree/{category_tree_id}/get_category_suggestions: get: tags: - "category_tree" summary: "Get Suggested Categories" description: "This call returns an array of category tree leaf nodes in the\ \ specified category tree that are considered by eBay to most closely correspond\ \ to the query string q. Returned with each suggested node is a localized\ \ name for that category (based on the Accept-Language header specified\ \ for the call), and details about each of the category's ancestor nodes,\ \ extending from its immediate parent up to the root of the category tree.

You\ \ identify the tree using the category_tree_id parameter, which was\ \ returned by the getDefaultCategoryTreeId call in the categoryTreeId\ \ field.

Important: This call is not supported in the Sandbox environment.\ \ It will return a response payload in which the categoryName fields\ \ contain random or boilerplate text regardless of the query submitted." operationId: "getCategorySuggestions" parameters: - name: "category_tree_id" in: "path" description: "The unique identifier of the eBay category tree. The category\ \ tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId\ \ method." required: true schema: type: "string" - name: "q" in: "query" description: "A quoted string that describes or characterizes the item being\ \ offered for sale. The string format is free form, and can contain any\ \ combination of phrases or keywords. eBay will parse the string and return\ \ suggested categories for the item." required: true schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/CategorySuggestionResponse" "400": description: "Bad Request" x-response-codes: errors: 62004: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category tree ID was not found." 62007: domain: "API_TAXONOMY" category: "REQUEST" description: "Missing keyword 'q'. Please specify a valid set of keywords\ \ that best describes your item." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "204": description: "No content" "404": description: "Not found" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" /category_tree/{category_tree_id}/get_item_aspects_for_category: get: tags: - "category_tree" description: "This call returns a list of aspects that are appropriate\ \ or necessary for accurately describing items in the specified leaf category.\ \ Each aspect identifies an item attribute (for example, color,) for which\ \ the seller will be required or encouraged to provide a value (or variation\ \ values) when offering an item in that category on eBay.

For each\ \ aspect, getItemAspectsForCategory provides complete metadata, including:\ \ Use this information\ \ to construct an interface through which sellers can enter or select the\ \ appropriate values for their items or item variations. Once you collect\ \ those values, include them as product aspects when creating inventory items\ \ using the Inventory API." operationId: "getItemAspectsForCategory" parameters: - name: "category_id" in: "query" description: "The unique identifier of the leaf category for which aspects\ \ are being requested.

Note:\ \ If the category_id submitted does not identify a leaf node of the\ \ tree, this call returns an error. " required: true schema: type: "string" - name: "category_tree_id" in: "path" description: "The unique identifier of the eBay category tree. The category\ \ tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId\ \ method." required: true schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/AspectMetadata" "400": description: "Bad Request" x-response-codes: errors: 62004: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category tree ID was not found." 62005: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category ID does not belong to specified\ \ category tree." 62006: domain: "API_TAXONOMY" category: "REQUEST" description: "Missing category ID." 62008: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category ID is the root for the category\ \ tree." 62009: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category ID must be a leaf category." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "204": description: "No Content" "404": description: "Not found" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" - "https://api.ebay.com/oauth/api_scope/metadata.insights" /category_tree/{category_tree_id}/get_compatibility_properties: get: tags: - "category_tree" summary: "Get Compatibility Properties" description: "This call retrieves the compatible vehicle aspects that are used\ \ to define a motor vehicle that is compatible with a motor vehicle part or\ \ accessory. The values that are retrieved here might include motor vehicle\ \ aspects such as 'Make', 'Model', 'Year', 'Engine', and 'Trim', and each\ \ of these aspects are localized for the eBay marketplace.

The category_tree_id\ \ value is passed in as a path parameter, and this value identifies the eBay\ \ category tree. The category_id value is passed in as a\ \ query parameter, as this parameter is also required. The specified category\ \ must be a category that supports parts compatibility.

At this time,\ \ this operation only supports parts and accessories listings for cars, trucks,\ \ and motorcycles (not boats, power sports, or any other vehicle types). Only\ \ the following eBay marketplaces support parts compatibility:" operationId: "getCompatibilityProperties" parameters: - name: "category_tree_id" in: "path" description: "This is the unique identifier of category tree. The following\ \ is the list of category_tree_id values and the eBay marketplaces\ \ that they represent. One of these ID values must be passed in as a path\ \ parameter, and the category_id value, that is passed\ \ in as query parameter, must be a valid eBay category on that eBay marketplace\ \ that supports parts compatibility for cars, trucks, or motorcycles.

" required: true schema: type: "string" - name: "category_id" in: "query" description: "The unique identifier of an eBay category. This eBay category\ \ must be a valid eBay category on the specified eBay marketplace, and the\ \ category must support parts compatibility for cars, trucks, or motorcycles.

\ \ The getAutomotivePartsCompatibilityPolicies method of the Selling\ \ Metadata API can be used to retrieve all eBay categories for an eBay marketplace\ \ that support parts compatibility for vehicles." required: true schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/GetCompatibilityMetadataResponse" "400": description: "Bad Request" x-response-codes: errors: 62004: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category tree ID was not found." 62005: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category ID does not belong to specified\ \ category tree." 62101: domain: "API_TAXONOMY" category: "REQUEST" description: "This category ID is disabled for parts compatibility." 62006: domain: "API_TAXONOMY" category: "REQUEST" description: "Missing category ID." 62103: domain: "API_TAXONOMY" category: "REQUEST" description: "The CategoryTreeId is not supported." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "204": description: "No content" "404": description: "Not found" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" /category_tree/{category_tree_id}/get_compatibility_property_values: get: tags: - "category_tree" summary: "Get Compatibility Property Values" description: "This call retrieves applicable compatible vehicle property values\ \ based on the specified eBay marketplace, specified eBay category, and filters\ \ used in the request. Compatible vehicle properties are returned in the compatibilityProperties.name\ \ field of a getCompatibilityProperties response.

\ \ One compatible vehicle property applicable to the specified eBay marketplace\ \ and eBay category is specified through the required compatibility_property\ \ filter. Then, the user has the option of further restricting the compatible\ \ vehicle property values that are returned in the response by specifying\ \ one or more compatible vehicle property name/value pairs through the filter\ \ query parameter.

See the documentation in URI parameters\ \ section for more information on using the compatibility_property\ \ and filter query parameters together to customize the data\ \ that is retrieved." operationId: "getCompatibilityPropertyValues" parameters: - name: "category_tree_id" in: "path" description: "This is the unique identifier of the category tree. The following\ \ is the list of category_tree_id values and the eBay marketplaces\ \ that they represent. One of these ID values must be passed in as a path\ \ parameter, and the category_id value, that is passed\ \ in as query parameter, must be a valid eBay category on that eBay marketplace\ \ that supports parts compatibility for cars, trucks, or motorcycles.

" required: true schema: type: "string" - name: "compatibility_property" in: "query" description: "One compatible vehicle property applicable to the specified\ \ eBay marketplace and eBay category is specified in this required filter.\ \ Compatible vehicle properties are returned in the compatibilityProperties.name\ \ field of a getCompatibilityProperties response.

\ \ For example, if you wanted to retrieve all vehicle trims for a 2018 Toyota\ \ Camry, you would set this filter as follows: compatibility_property=Trim\ \ and then include the following three name/value filters through one filter\ \ parameter: filter=Year:2018,Make:Toyota,Model:Camry.

So,\ \ putting this all together, the URI would look something like this:

GET\
          \ https://api.ebay.com/commerce/
taxonomy/v1/category_tree/100/
get_compatibility_property_values?
category_id=6016&compatibility_property=Trim
&filter=Year:2018,Make:Toyota,Model:Camry
" required: true schema: type: "string" - name: "category_id" in: "query" description: "The unique identifier of an eBay category. This eBay category\ \ must be a valid eBay category on the specified eBay marketplace, and the\ \ category must support parts compatibility for cars, trucks, or motorcycles.

\ \ The getAutomotivePartsCompatibilityPolicies method of\ \ the Selling Metadata API can be used to retrieve all eBay categories for\ \ an eBay marketplace that support parts compatibility for vehicles." required: true schema: type: "string" - name: "filter" in: "query" description: "One or more compatible vehicle property name/value pairs are\ \ passed in through this query parameter. The compatible vehicle property\ \ name and corresponding value are delimited with a colon (:), such as filter=Year:2018,\ \ and multiple compatible vehicle property name/value pairs are delimited\ \ with a comma (,).

Note: Commas\ \ are used as delimiters between filter values. If a value includes a comma\ \ (e.g., BodyStyle:AWD B9 8W5,C8WD) you must\ \ include a backslash (\\) immediately before the comma to prevent\ \ it from being evaluated as a delimiter.

As with all query parameter\ \ values, the filter parameters must be URL encoded. For more information\ \ about encoding request parameters, refer to URL encoding query parameter values.
For\ \ example, to retrieve all vehicle trims for a 2022 Audi A4:The resulting comma-separated filter\ \ query parameter is:
filter=Year:2022,Make:Audi,Model:A4,BodyStyle:AWD\
          \ B9 8W5\\,8WD

The following sample shows the same filter\ \ but with URL encoding for the blank spaces.
GET https://api.ebay.com/commerce/
taxonomy/v1/category_tree/100/
get_compatibility_property_values?category_id=6016&compatibility_property=Trim&filter=Year:2022,Make:Audi,Model:A4,BodyStyle:AWD%20B9%208W5%5C%2C8WD

Note: While not required, it is strongly recommended\ \ that users limit the size of the result set by using the filter\ \ query parameter. Failure to do so may result in a timeout error if too\ \ much data is attempted to be returned. For implementation help,\ \ refer to eBay API documentation at https://developer.ebay.com/api-docs/commerce/taxonomy/types/txn:ConstraintFilter" required: false schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/GetCompatibilityPropertyValuesResponse" "400": description: "Bad Request" x-response-codes: errors: 62004: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category tree ID was not found." 62100: domain: "API_TAXONOMY" category: "REQUEST" description: "The filter format is invalid. For more information,\ \ see the API call reference documentation." 62005: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category ID does not belong to specified\ \ category tree." 62101: domain: "API_TAXONOMY" category: "REQUEST" description: "This category ID is disabled for parts compatibility." 62006: domain: "API_TAXONOMY" category: "REQUEST" description: "Missing category ID." 62102: domain: "API_TAXONOMY" category: "REQUEST" description: "The compatibility property is invalid." 62103: domain: "API_TAXONOMY" category: "REQUEST" description: "The CategoryTreeId is not supported." 62104: domain: "API_TAXONOMY" category: "REQUEST" description: "Missing compatibility property." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "204": description: "No content" "404": description: "Not found" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" /category_tree/{category_tree_id}/get_expired_categories: get: tags: - "category_tree" description: "This method retrieves the mappings of expired leaf categories\ \ in the specified category tree to their corresponding active leaf categories.\ \ Note that in some cases, several expired categories are mapped to a single\ \ active category.

Note: This method\ \ only returns information about categories that have been mapped (i.e., combined\ \ categories and split categories). It does not return information about expired\ \ categories that have no corresponding active categories. When a category\ \ expires in this manner, any completed items that were listed in the expired\ \ category can still be found, but new listings cannot be created in the category." operationId: "getExpiredCategories" parameters: - name: "category_tree_id" in: "path" description: "The unique identifier of the eBay category tree.

The\ \ category tree ID for an eBay marketplace can be retrieved using the getDefaultCategoryTreeId method." required: true schema: type: "string" responses: "200": description: "Success" content: application/json: schema: $ref: "#/components/schemas/ExpiredCategories" "400": description: "Bad Request" x-response-codes: errors: 62004: domain: "API_TAXONOMY" category: "REQUEST" description: "The specified category tree ID was not found." 62103: domain: "API_TAXONOMY" category: "REQUEST" description: "The CategoryTreeId is not supported." "500": description: "Internal Server Error" x-response-codes: errors: 62000: domain: "API_TAXONOMY" category: "APPLICATION" description: "There was a problem with an eBay internal system or\ \ process. Contact eBay developer support for assistance." "204": description: "No content" "404": description: "Not found" security: - api_auth: - "https://api.ebay.com/oauth/api_scope" components: schemas: AncestorReference: type: "object" properties: categoryId: type: "string" description: "The unique identifier of the eBay ancestor category.

Note: The root node of a full\ \ default category tree includes the categoryId field, but its\ \ value should not be relied upon. It provides no useful information for\ \ application development." categoryName: type: "string" description: "The name of the ancestor category identified by categoryId." categorySubtreeNodeHref: type: "string" description: "The href portion of the getCategorySubtree call that\ \ retrieves the subtree below the ancestor category node." categoryTreeNodeLevel: type: "integer" description: "The absolute level of the ancestor category node in the hierarchy\ \ of its category tree.

Note:\ \ The root node of any full category tree is always at level 0.\ \ " format: "int32" description: "This type contains information about one of the ancestors of a\ \ suggested category. An ordered list of these references describes the path\ \ from the suggested category to the root of the category tree it belongs\ \ to." Aspect: type: "object" properties: aspectConstraint: description: "Information about the formatting, occurrence, and support\ \ of this aspect." $ref: "#/components/schemas/AspectConstraint" aspectValues: type: "array" description: "A list of valid values for this aspect (for example: Red,\ \ Green, and Blue), along with any constraints\ \ on those values." items: $ref: "#/components/schemas/AspectValue" localizedAspectName: type: "string" description: "The localized name of this aspect (for example: Colour\ \ on the eBay UK site).

Note:\ \ This name is always localized for the specified marketplace. " relevanceIndicator: description: "The relevance of this aspect. This field is returned if eBay\ \ has data on how many searches have been performed for listings in the\ \ category using this item aspect.

Note:\ \ This container is restricted to applications that have been granted\ \ permission to access this feature. You must submit an App Check ticket to request this access. In the App Check form,\ \ add a note to the Application Title/Summary and/or Application\ \ Details fields that you want access to 'Buyer Demand Data' in the\ \ Taxonomy API." $ref: "#/components/schemas/RelevanceIndicator" description: "This type contains information about an item attribute (for example,\ \ color) that is appropriate or necessary for accurately describing items\ \ in a particular leaf category. Sellers are required or encouraged to provide\ \ one or more values of this aspect when offering an item in that category\ \ on eBay." AspectConstraint: type: "object" properties: aspectApplicableTo: type: "array" description: "This value indicate if the aspect identified by the aspects.localizedAspectName\ \ field is a product aspect (relevant to catalog products in the category)\ \ or an item/instance aspect, which is an aspect whose value will vary\ \ based on a particular instance of the product." items: type: "string" description: " For implementation help, refer to eBay\ \ API documentation" aspectDataType: type: "string" description: "The data type of this aspect. For implementation help, refer\ \ to eBay\ \ API documentation" aspectEnabledForVariations: type: "boolean" description: "A value of true indicates that this aspect can\ \ be used to help identify item variations." aspectFormat: type: "string" description: "Returned only if the value of aspectDataType\ \ identifies a data type that requires specific formatting. Currently,\ \ this field provides formatting hints as follows:
  • DATE:\ \ YYYY, YYYYMM, YYYYMMDD
  • NUMBER:\ \ int32, double
" aspectMaxLength: type: "integer" description: "The maximum length of the item/instance aspect's value. The\ \ seller must make sure not to exceed this length when specifying the\ \ instance aspect's value for a product. This field is only returned for\ \ instance aspects." format: "int32" aspectMode: type: "string" description: "The manner in which values of this aspect must be specified\ \ by the seller (as free text or by selecting from available options).\ \ For implementation help, refer to eBay\ \ API documentation" aspectRequired: type: "boolean" description: "A value of true indicates that this aspect is\ \ required when offering items in the specified category." aspectUsage: type: "string" description: "The enumeration value returned in this field will indicate\ \ if the corresponding aspect is recommended or optional.

Note: This field is always returned,\ \ even for hard-mandated/required aspects (where aspectRequired:\ \ true). The value returned for required aspects will be RECOMMENDED,\ \ but they are actually required and a seller will be blocked from listing\ \ or revising an item without these aspects. For implementation\ \ help, refer to eBay\ \ API documentation" expectedRequiredByDate: type: "string" description: "The expected date after which the aspect will be required.

Note: The value returned in this\ \ field specifies only an approximate date, which may not reflect the\ \ actual date after which the aspect is required." itemToAspectCardinality: type: "string" description: "Indicates whether this aspect can accept single or multiple\ \ values for items in the specified category.

Note: Up to 30 values can be supplied for aspects that\ \ accept multiple values. For implementation help, refer to eBay\ \ API documentation" aspectAdvancedDataType: type: "string" description: "Indicates additional data type requirements for the aspect.\ \ For example, NUMERIC_RANGE indicates that the aspect value\ \ must be in numeric range format.

Note:\ \ Currently only NUMERIC_RANGE is supported. For implementation\ \ help, refer to eBay\ \ API documentation" description: "This type contains information about the formatting, occurrence,\ \ and support of an aspect." AspectMetadata: type: "object" properties: aspects: type: "array" description: "A list of item aspects (for example, color) that are appropriate\ \ or necessary for accurately describing items in a particular leaf category.\ \ Each category has a different set of aspects and different requirements\ \ for aspect values. Sellers are required or encouraged to provide one\ \ or more acceptable values for each aspect when offering an item in that\ \ category on eBay." items: $ref: "#/components/schemas/Aspect" description: "This type is the container type for the response payload of the\ \ getItemAspectsForCategory call." AspectValue: type: "object" properties: localizedValue: type: "string" description: "The localized value of this aspect.

Note: This value is always localized\ \ for the specified marketplace. " valueConstraints: type: "array" description: "Not returned if the value of the localizedValue\ \ field can always be selected for this aspect of the specified category.

Contains\ \ a list of the dependencies that identify when the value of the localizedValue\ \ field is available for the current aspect. Each dependency specifies\ \ the values of another aspect of the same category (a control\ \ aspect), for which the current value of the current aspect can also\ \ be selected by the seller.

Example: A shirt\ \ is available in three sizes and three colors, but only the Small and\ \ Medium sizes come in Green. Thus for the Color aspect, the value Green\ \ is constrained by its dependency on Size (the control aspect). Only\ \ when the Size aspect value is Small or Medium, can the Color aspect\ \ value of Green be selected by the seller." items: $ref: "#/components/schemas/ValueConstraint" description: "This type contains a valid value for an aspect, along with any\ \ constraints on the occurrence of that value." BaseCategoryTree: type: "object" properties: categoryTreeId: type: "string" description: "The unique identifier of the eBay category tree for the specified\ \ marketplace." categoryTreeVersion: type: "string" description: "The version of the category tree identified by categoryTreeId.\ \ It's a good idea to cache this value for comparison so you can determine\ \ if this category tree has been modified in subsequent calls." description: "This type contains identifying information for the category tree\ \ associated with a particular eBay marketplace." Category: type: "object" properties: categoryId: type: "string" description: "The unique identifier of the eBay category within its category\ \ tree.

Note: The root\ \ node of a full default category tree includes the categoryId\ \ field, but its value should not be relied upon. It provides no useful\ \ information for application development. " categoryName: type: "string" description: "The name of the category identified by categoryId." description: "This type contains information about a particular eBay category." CategoryAspect: type: "object" properties: category: description: "The details that are appropriate or necessary to accurately\ \ define the category." $ref: "#/components/schemas/Category" aspects: type: "array" description: "A list of aspect metadata that is used to describe the items\ \ in a particular leaf category." items: $ref: "#/components/schemas/Aspect" CategorySubtree: type: "object" properties: categorySubtreeNode: description: "Contains details of all nodes of the category subtree hierarchy\ \ below a specified node. This is a recursive structure." $ref: "#/components/schemas/CategoryTreeNode" categoryTreeId: type: "string" description: "The unique identifier of the eBay category tree to which this\ \ subtree belongs." categoryTreeVersion: type: "string" description: "The version of the category tree identified by categoryTreeId.\ \ It's a good idea to cache this value for comparison so you can determine\ \ if this category tree has been modified in subsequent calls." description: "This type contains information about a particular subtree of a\ \ specified eBay category tree. A category subtree consists of a non-root\ \ node of the category tree, and all of its descendants down to the leaf nodes." CategorySuggestion: type: "object" properties: category: description: "Contains details about the suggested category." $ref: "#/components/schemas/Category" categoryTreeNodeAncestors: type: "array" description: "An ordered list of category references that describes the\ \ location of the suggested category in the specified category tree. The\ \ list identifies the category's ancestry as a sequence of parent nodes,\ \ from the current node's immediate parent to the root node of the category\ \ tree.

Note: The root\ \ node of a full default category tree includes categoryId and\ \ categoryName fields, but their values should not be relied upon.\ \ They provide no useful information for application development." items: $ref: "#/components/schemas/AncestorReference" categoryTreeNodeLevel: type: "integer" description: "The absolute level of the category tree node in the hierarchy\ \ of its category tree.

Note:\ \ The root node of any full category tree is always at level 0." format: "int32" relevancy: type: "string" description: "This field is reserved for internal or future use." description: "This type contains information about a suggested category tree\ \ leaf node that corresponds to keywords provided in the request. It includes\ \ details about each of the category's ancestor nodes extending up to the\ \ root of the category tree." CategorySuggestionResponse: type: "object" properties: categorySuggestions: type: "array" description: "Contains details about one or more suggested categories that\ \ correspond to the provided keywords. The array of suggested categories\ \ is sorted in order of eBay's confidence of the relevance of each category\ \ (the first category is the most relevant).

Important: This call\ \ is not supported in the Sandbox environment. It will return a response\ \ payload in which the categoryName fields contain random or boilerplate\ \ text regardless of the query submitted. " items: $ref: "#/components/schemas/CategorySuggestion" categoryTreeId: type: "string" description: "The unique identifier of the eBay category tree from which\ \ suggestions are returned." categoryTreeVersion: type: "string" description: "The version of the category tree identified by categoryTreeId.\ \ It's a good idea to cache this value for comparison so you can determine\ \ if this category tree has been modified in subsequent calls." description: "This type contains an array of suggested category tree nodes that\ \ are considered by eBay to most closely correspond to the keywords provided\ \ in a query string, from a specified category tree." CategoryTree: type: "object" properties: applicableMarketplaceIds: type: "array" description: "A list of one or more identifiers of the eBay marketplaces\ \ that use this category tree." items: type: "string" description: " For implementation help, refer to eBay\ \ API documentation" categoryTreeId: type: "string" description: "The unique identifier of this eBay category tree." categoryTreeVersion: type: "string" description: "The version of this category tree. It's a good idea to cache\ \ this value for comparison so you can determine if this category tree\ \ has been modified in subsequent calls." rootCategoryNode: description: "Contains details of all nodes of the category tree hierarchy,\ \ starting with the root node and down to the leaf nodes. This is a recursive\ \ structure.

Note:\ \ The root node of a full default category tree includes the categoryId\ \ field, but its value should not be relied upon. It provides no useful\ \ information for application development." $ref: "#/components/schemas/CategoryTreeNode" description: "This type contains information about all nodes of a specified\ \ eBay category tree." CategoryTreeNode: type: "object" properties: category: description: "Contains details about the current category tree node." $ref: "#/components/schemas/Category" categoryTreeNodeLevel: type: "integer" description: "The absolute level of the current category tree node in the\ \ hierarchy of its category tree.

Note:\ \ The root node of any full category tree is always at level 0.\ \ " format: "int32" childCategoryTreeNodes: type: "array" description: "An array of one or more category tree nodes that are the immediate\ \ children of the current category tree node, as well as their children,\ \ recursively down to the leaf nodes.

Returned only if the\ \ current category tree node is not a leaf node (the value of leafCategoryTreeNode\ \ is false)." items: $ref: "#/components/schemas/CategoryTreeNode" leafCategoryTreeNode: type: "boolean" description: "A value of true indicates that the current category\ \ tree node is a leaf node (it has no child nodes). A value of false\ \ indicates that the current node has one or more child nodes, which are\ \ identified by the childCategoryTreeNodes array.

Returned\ \ only if the value of this field is true." parentCategoryTreeNodeHref: type: "string" description: "The href portion of the getCategorySubtree call that\ \ retrieves the subtree below the parent of this category tree node.

Not\ \ returned if the current category tree node is the root node of its\ \ tree." description: "This type contains information about all nodes of a category tree\ \ or subtree hierarchy, including and below the specified Category,\ \ down to the leaf nodes. It is a recursive structure." CompatibilityProperty: type: "object" properties: name: type: "string" description: "This is the actual name of the compatible vehicle property\ \ as it is known on the specified eBay marketplace and in the eBay category.\ \ This is the string value that should be used in the compatibility_property\ \ and filter query parameters of a getCompatibilityPropertyValues\ \ request URI.

Typical vehicle properties are 'Make', 'Model',\ \ 'Year', 'Engine', and 'Trim', but will vary based on the eBay marketplace\ \ and the eBay category." localizedName: type: "string" description: "This is the localized name of the compatible vehicle property.\ \ The language that is used will depend on the user making the call, or\ \ based on the language specified if the Content-Language\ \ HTTP header is used.

In some instances, the string value in this\ \ field may be the same as the string in the corresponding name\ \ field." description: "This type is used by the compatibilityProperties\ \ array that is returned in the getCompatibilityProperties\ \ call. The compatibilityProperties container consists of\ \ an array of all compatible vehicle properties applicable to the specified\ \ eBay marketplace and eBay category ID." CompatibilityPropertyValue: type: "object" properties: value: type: "string" description: "Each value field shows one applicable compatible\ \ vehicle property value. The values that are returned will depend on\ \ the specified eBay marketplace, specified eBay category, and filters\ \ in the request." description: "This type is used by the compatibilityPropertyValues\ \ array that is returned in the getCompatibilityPropertyValues\ \ response. The compatibilityPropertyValues array contains\ \ all compatible vehicle property values that match the specified eBay marketplace,\ \ specified eBay category, and filters in the request. If the compatibility_property\ \ parameter value in the request is 'Trim', each value returned in each value\ \ field will be a different vehicle trim, applicable to any filters that are\ \ set in the filter query parameter of the request, and also\ \ based on the eBay marketplace and category specified in the call request." 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." ExpiredCategories: type: "object" properties: expiredCategories: type: "array" description: "An array of expired category ID(s) for the requested category\ \ tree, and the currently active category ID(s) that have replaced them." items: $ref: "#/components/schemas/ExpiredCategory" description: "This type is used by the getExpiredCategories response\ \ to indicate any eBay leaf categories in the specified category tree that\ \ have expired and the currently active leaf categories that have replaced\ \ them." ExpiredCategory: type: "object" properties: fromCategoryId: type: "string" description: "The unique identifier of the expired eBay leaf category." toCategoryId: type: "string" description: "The unique identifier of the currently active eBay leaf category\ \ that has replaced the expired leaf category.

Note: More than one fromCategoryID value may map into the\ \ same toCategoryID value, as multiple eBay categories may be consolidated\ \ into one new, expanded category." description: "This type defines the expired category ID for the requested category\ \ tree, and the currently active category ID that has replaced it." GetCategoriesAspectResponse: type: "object" properties: categoryTreeId: type: "string" description: "The unique identifier of the eBay category tree being requested." categoryTreeVersion: type: "string" description: "The version of the category tree that is returned in the categoryTreeId\ \ field." categoryAspects: type: "array" description: "An array of aspects that are appropriate or necessary for\ \ accurately describing items in a particular leaf category." items: $ref: "#/components/schemas/CategoryAspect" GetCompatibilityMetadataResponse: type: "object" properties: compatibilityProperties: type: "array" description: "This container consists of an array of all compatible vehicle\ \ properties applicable to the specified eBay marketplace and eBay category\ \ ID." items: $ref: "#/components/schemas/CompatibilityProperty" description: "This type is used by the base response of the getCompatibilityProperties\ \ method." GetCompatibilityPropertyValuesResponse: type: "object" properties: compatibilityPropertyValues: type: "array" description: "This array contains all compatible vehicle property values\ \ that match the specified eBay marketplace, specified eBay category,\ \ and filters in the request. If the compatibility_property\ \ parameter value in the request is 'Trim', each value returned in each\ \ value field will be a different vehicle trim, applicable\ \ to any filters that are set in the filter query parameter\ \ of the request, and also based on the eBay marketplace and category\ \ specified in the call request." items: $ref: "#/components/schemas/CompatibilityPropertyValue" description: "The base response type of the getCompatibilityPropertyValues\ \ method." RelevanceIndicator: type: "object" properties: searchCount: type: "integer" description: "The number of recent searches (based on 30 days of data) for\ \ the aspect." format: "int32" description: "The relevance of this aspect. This field is returned if eBay has\ \ data on how many searches have been performed for listings in the category\ \ using this item aspect.

Note:\ \ This container is restricted to applications that have been granted permission\ \ to access this feature. You must submit an App Check ticket to request this access. In the App Check form, add\ \ a note to the Application Title/Summary and/or Application Details\ \ fields that you want access to 'Buyer Demand Data' in the Taxonomy API." ValueConstraint: type: "object" properties: applicableForLocalizedAspectName: type: "string" description: "The name of the control aspect on which the current aspect\ \ value depends." applicableForLocalizedAspectValues: type: "array" description: "Contains a list of the values of the control aspect on which\ \ this aspect's value depends. When the control aspect has any of the\ \ specified values, the current value of the current aspect will also\ \ be available." items: type: "string" description: "This type contains a list of the dependencies that identify when\ \ a particular value is available for a given aspect of a given category.\ \ Each dependency specifies the values of another aspect of the same category\ \ (the control aspect), for which the given value of the given aspect\ \ can also be selected by the seller. This container consists of constraint\ \ information for the corresponding product aspect value." securitySchemes: api_auth: type: "oauth2" description: "The security definitions for this API. Please check individual\ \ operations for applicable scopes." flows: clientCredentials: tokenUrl: "https://api.ebay.com/identity/v1/oauth2/token" scopes: https://api.ebay.com/oauth/api_scope: "View public data from eBay" https://api.ebay.com/oauth/api_scope/metadata.insights: "View metadata\ \ insights such as aspect relevance."