taxonomy APIv1_beta.2.0

getItemAspectsForCategory

GET
/category_tree/{category_tree_id}/get_item_aspects_for_category
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:
  • The aspect's data type, format, and entry mode
  • Whether the aspect is required in listings
  • Whether the aspect can be used for item variations
  • Whether the aspect accepts multiple values for an item
  • Allowed values for the aspect
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.

Input

Resource URI (production)

GET https://api.ebay.com/commerce/taxonomy/v1_beta/category_tree/{category_tree_id}/get_item_aspects_for_category?

URI parameters

ParameterTypeDescription
category_idstringThe 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.

Occurrence: Required

category_tree_idstringThe unique identifier of the eBay category tree from which the specified category's aspects are being requested.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the client grant flow, using one scope from the following list:

https://api.ebay.com/oauth/api_scope

See OAuth access tokens for more information.

Output

HTTP response headers

Output container/fieldTypeDescription
aspectsarray of AspectA list of item attributes (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.

Occurrence: Always

aspects.aspectConstraintAspectConstraintContains information about the formatting, occurrence, and support of this aspect.

Occurrence: Always

aspects.aspectConstraint.aspectApplicableToarray of AspectApplicableToEnumThis 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.

Occurrence: Conditional

aspects.aspectConstraint.aspectDataTypeAspectDataTypeEnumThe data type of this aspect.

Occurrence: Always

aspects.aspectConstraint.aspectEnabledForVariationsbooleanA value of true indicates that this aspect can be used to help identify item variations.

Occurrence: Always

aspects.aspectConstraint.aspectFormatstringReturned 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

Occurrence: Conditional

aspects.aspectConstraint.aspectMaxLengthintegerThe 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.

Occurrence: Conditional

aspects.aspectConstraint.aspectModeAspectModeEnumThe manner in which values of this aspect must be specified by the seller (as free text or by selecting from available options).

Occurrence: Always

aspects.aspectConstraint.aspectRequiredbooleanA value of true indicates that this aspect is required when offering items in the specified category.

Occurrence: Always

aspects.aspectConstraint.itemToAspectCardinalityItemToAspectCardinalityEnumIndicates whether this aspect can accept single or multiple values for items in the specified category.

Occurrence: Always

aspects.aspectValuesarray of AspectValueContains a list of valid values for this aspect (for example: Red, Green, and Blue), along with any constraints on those values.

Occurrence: Always

aspects.aspectValues.localizedValuestringThe localized value of this aspect.

Note: This value is always localized for the specified marketplace. There is no canonical version of this value.

Occurrence: Always

aspects.aspectValues.valueConstraintsarray of ValueConstraintNot 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.

Occurrence: Conditional

aspects.aspectValues.valueConstraints.applicableForLocalizedAspectNamestringThe name of the control aspect on which the current aspect value depends.

Occurrence: Conditional

aspects.aspectValues.valueConstraints.applicableForLocalizedAspectValuesarray of stringContains 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.

Occurrence: Conditional

aspects.localizedAspectNamestringThe localized name of this aspect (for example: colour on the eBay UK site).

Note: This name is always localized for the specified marketplace. There is no canonical aspect name.

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200Success
204No Content
400Bad Request
404Not found
500Internal Server Error

Error codes

CodeDomainCategoryMeaning
62000API_TAXONOMYAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
62004API_TAXONOMYREQUESTThe specified category tree ID was not found.
62005API_TAXONOMYREQUESTThe specified category ID does not belong to specified category tree.
62006API_TAXONOMYREQUESTMissing category ID.
62008API_TAXONOMYREQUESTThe specified category ID is the root for the category tree.
62009API_TAXONOMYREQUESTThe specified category ID must be a leaf category.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Get aspects for a leaf category

This sample returns an array of aspects that are appropriate or necessary for accurately describing items in the specified leaf category.

Input

Use the category_tree_id path parameter to specify the category tree, and use the category_id query parameter to specify the leaf category for which to retrieve associated aspects.
GET
https://api.ebay.com/commerce/taxonomy/v1_beta/category_tree/0/get_item_aspects_for_category?category_id=67726

Output

A successful call returns a list of the aspects associated with category 67726, including each aspect's data type, format, entry mode, cardinality, and support. It also returns a list of valid values for each aspect, including any constraints on the applicability of each value.