catalog APIv1_beta.3.0

getProductMetadataForCategories

GET
/get_product_metadata_for_categories
This call retrieves an array of all supported aspects, aspect constraints, and aspect values for the specified eBay categories. The array is a union (with duplicates removed) of all returned aspects.

After using the search and getProduct calls to find a catalog product that matches a seller's inventory item, you may determine that a matching product does not exist in the eBay catalog. You can propose a new product for the catalog by taking the following steps:
  1. Use the Taxonomy API's category_tree calls to discover the appropriate category or categories for the seller's inventory item. See Finding categories for a listing or promotion.
  2. Use getProductMetadataForCategories to determine the aspects of your selected categories that should be associated with your new product.
  3. Use the createChangeRequest call to to submit a change request to add the new product to the eBay catalog for your seller's marketplace.
Note: The X-EBAY-C-MARKETPLACE-ID request header is required to identify the user's business context. At least one eBay category ID is required and is specified through the primary_category_id query parameter.

Input

Resource URI (production)

GET https://api.ebay.com/commerce/catalog/v1_beta/get_product_metadata_for_categories?

URI parameters

ParameterTypeDescription
other_applicable_category_idsarray of stringA string of comma-separated category IDs. if sellers want to specify more than the primary category under which to offer a product, they can use this parameter to retrieve the aspects associated with all of the additional specified categories.

eBay category IDs are returned by the Taxonomy API's category_tree calls.

Occurrence: Optional

primary_category_idstringThe unique identifier of the primary eBay category for which you will retrieve product aspects.

eBay category IDs are returned by the Taxonomy API's category_tree calls.

Occurrence: Required

HTTP request headers

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

This call also uses the X-EBAY-C-MARKETPLACE-ID header to identify the user's business context. This header is currently limited to EBAY-US, EBAY-AU, EBAY-CA, and EBAY-GB values. If not included with your request, the marketplace value defaults to EBAY-US. Note that it does not indicate a language preference or end-user location.

Examples:
X-EBAY-C-MARKETPLACE-ID: EBAY-US
X-EBAY-C-MARKETPLACE-ID: EBAY-AU

HeaderTypeDescription
Accept-LanguagestringThis request header sets the natural language that will be provided in the field values of the response payload. Supported values for this header can be found in the Marketplace ID and language header values table.

Occurrence: Strongly Recommended

X-EBAY-C-MARKETPLACE-IDstringUse this header to specify the eBay marketplace identifier. Supported values for this header can be found under Supported marketplaces on the Catalog API Overview page.

Occurrence: Required

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.

Note: Only the sell.inventory scope is required for selling applications, and only the commerce.catalog.readonly scope is required for buying applications.

Output

HTTP response headers

{ /* ProductMetadataForCategories */ }
Output container/fieldTypeDescription
aspectsarray of CategoryAspectContains information about one or more required and recommended product aspects associated with the specified eBay category or categories. This is a union (with duplicates removed) of all aspects associated with the specified categories.

Occurrence: Conditional

aspects.aspectHelpTextstringReturned only if this field is populated. This provides information and context for the category aspect. The help text can be presented to the seller to clarify the intended purpose of this aspect, and recommendations for its use. For example, the help text for the Country/Region of Manufacture aspect is:

Specifying the country/region of manufacture can help streamline customs clearance.

Occurrence: Conditional

aspects.constraintProductAspectConstraintContains information about the input and formatting constraints of the category aspect, including the data type and format, input mode, occurrence, and cardinality.

Occurrence: Always

aspects.constraint.aspectDataTypeAspectDataTypeEnumThe data type used to represent the aspect. See the AspectDataTypeEnum type for more information about each data type.

Occurrence: Conditional

aspects.constraint.aspectFormatstringReturned only if the value of aspectDataType is STRING or NUMBER. The required format for date or number values (e.g. a date value may be expressed as MMYYYY or MMYY).

Occurrence: Conditional

aspects.constraint.aspectModeAspectModeEnumIndicates whether the seller must select from a closed list of aspect values, or can input the aspect value manually.

Occurrence: Conditional

aspects.constraint.aspectRequiredbooleanA value of true indicates that the aspect is mandatory for products listed in this category.

Occurrence: Conditional

aspects.constraint.importanceImportanceEnumThis value indicates the level of importance of the product identifier appearing in the catalog product.

Occurrence: Conditional

aspects.constraint.productToAspectCardinalityItemToAspectCardinalityEnumIndicates whether the aspect requires only one value, or can accept multiple values when listing in this category. An example of a product aspect that will often have numerous values is Features.

Occurrence: Conditional

aspects.namestringThe name of the category aspect.

Occurrence: Always

aspects.valuesarray of CategoryAspectValueNot returned if the value of the constraint field is FREE_TEXT and there are no stored values for this aspect. Contains information about one or more supported values for the category identified by the name field), as well as constraint information for those values.

Occurrence: Conditional

aspects.values.valuestringA supported value of the corresponding category aspect (shown in the aspects.name field). Every supported value for the category aspect is shown in the aspects.values container.

Occurrence: Conditional

aspects.values.valueConstraintsarray of ValueConstraintNot returned if the value of the value field can always be selected for this aspect of the specified category (that is, when no constraints apply to using the value).

Contains a list of the dependencies that identify when the value of the value 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.values.valueConstraints.applicableForAspectNamestringThe name of the control aspect on which the current aspect value depends.

Occurrence: Conditional

aspects.values.valueConstraints.applicableForAspectValuesarray 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

brandProductIdentifierContains information about available brand names, their input requirements, and their constraints for the specified categories.

Occurrence: Conditional

brand.constraintProductIdentifierConstraintContains information about the input, formatting, and occurrence constraints of the product identifier.

Occurrence: Conditional

brand.constraint.importanceImportanceEnumThis value indicates the level of importance of the product identifier appearing in the catalog product.

Occurrence: Conditional

brand.constraint.modeAspectModeEnumIndicates whether the seller must select from a closed list of identifier values, or can input the identifier manually.

Occurrence: Conditional

brand.constraint.requiredbooleanA value of true indicates that the identifier is mandatory for the product or categories specified.

Occurrence: Conditional

brand.valuesarray of stringA list of one or more valid values for this product identifier.

Occurrence: Conditional

eanProductIdentifierThe European Article Numbers (EANs) that identify this product.

Occurrence: Conditional

ean.constraintProductIdentifierConstraintContains information about the input, formatting, and occurrence constraints of the product identifier.

Occurrence: Conditional

ean.constraint.importanceImportanceEnumThis value indicates the level of importance of the product identifier appearing in the catalog product.

Occurrence: Conditional

ean.constraint.modeAspectModeEnumIndicates whether the seller must select from a closed list of identifier values, or can input the identifier manually.

Occurrence: Conditional

ean.constraint.requiredbooleanA value of true indicates that the identifier is mandatory for the product or categories specified.

Occurrence: Conditional

ean.valuesarray of stringA list of one or more valid values for this product identifier.

Occurrence: Conditional

isbnProductIdentifierThe International Standard Book Numbers (ISBNs) associated with the product.

Occurrence: Conditional

isbn.constraintProductIdentifierConstraintContains information about the input, formatting, and occurrence constraints of the product identifier.

Occurrence: Conditional

isbn.constraint.importanceImportanceEnumThis value indicates the level of importance of the product identifier appearing in the catalog product.

Occurrence: Conditional

isbn.constraint.modeAspectModeEnumIndicates whether the seller must select from a closed list of identifier values, or can input the identifier manually.

Occurrence: Conditional

isbn.constraint.requiredbooleanA value of true indicates that the identifier is mandatory for the product or categories specified.

Occurrence: Conditional

isbn.valuesarray of stringA list of one or more valid values for this product identifier.

Occurrence: Conditional

mpnProductIdentifierContains information about available Manufacturer Product Numbers (MPNs), their input requirements, and their constraints for the specified categories.

Occurrence: Conditional

upcProductIdentifierThe Universal Product Codes (UPCs) associated with the product.

Occurrence: Conditional

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
500Internal Server Error

Error codes

CodeDomainCategoryMeaning
75000API_CATALOGAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
75007API_CATALOGREQUESTCurrently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces}
75040API_CATALOGREQUESTThe specified category ID is invalid.
75041API_CATALOGREQUESTMissing query param primary category ID.
75045API_CATALOGREQUESTThe maximum number of Other Applicable Category Ids allowed is 4.

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 Category Metadata

This sample returns the details of aspects and their constraints and values that are associated with the specified categories.

Input

The input is a primary category ID and additional category IDs. There is no payload with this request.
GET
https://api.ebay.com/commerce/catalog/v1_beta/get_product_metadata_for_categories?primary_category_id=500&other_applicable_category_ids=34,36,63

Output

The aspect details are returned in the aspects container for categories 500, 34, 36, and 63. These aspects are combined into a single array (with duplicates removed) without reference to the categories.