catalog APIv1_beta.3.0

getProductMetadata

GET
/get_product_metadata
This call retrieves an array of all supported aspects, aspect constraints, and aspect values for the specified catalog product and its associated or suggested categories, as well as the values currently associated with that product. 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 discover a matching product, but determine that one or more product details are missing or inaccurate. You can propose updates to the product's aspects and aspect values 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 getProductMetadata to determine the aspects of your selected categories and the values of those aspects that should be added to the aspects and values already associated with your product.
  3. Use the createChangeRequest call to to submit a change request to update the product in 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. The eBay Product Identifier (ePID) for a catalog product is also required and is specified through the epid query parameter.

Input

Resource URI (production)

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

URI parameters

ParameterTypeDescription
other_applicable_category_idsarray of stringUse only if you are also including the primary_category_id parameter in the request. Provide one or more comma-separated category IDs in this parameter.

Sellers can use other_applicable_category_ids to retrieve information about the specified categories' associated aspects, constraints, and values, along with the same information for the category specified in the primary_category_id parameter, for the seller to assess, select, and populate for submission with the createChangeRequest call.

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

Occurrence: Optional

primary_category_idstringUse only if the seller believes this product is associated with the wrong primary category. Use this parameter to submit the unique identifier of the primary category that the seller wants to use instead. This call retrieves information about the specified category's associated aspects, constraints, and values for the seller to assess, select, and populate for submission with the Catalog API's createChangeRequest call.
  • If you exclude this parameter from your request, this call retrieves information about the aspects, constraints, and values of the specified product's current primary category and other applicable categories.
  • If you include this parameter in your request, this call does not return any information about the specified product's current primary or other applicable categories, but only about the specified category. To retrieve information about any other categories, you must specify them with the other_applicable_category_ids parameter.
eBay category IDs are returned by the Taxonomy API's category_tree calls.

Occurrence: Optional

epidstringThe unique eBay product identifier of the catalog product that you want to update. The supported and applied aspects, constraints, and values for this eBay catalog product are returned.

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 in the MarketplaceIdEnum type definition.

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

{ /* ProductMetadata */ }
Output container/fieldTypeDescription
aspectsarray of ProductMetadataAspectContains information about one or more aspects that are supported for the specified catalog product, including those that are currently associated with the product. This is a union (with duplicates removed) of all aspects associated with the specified category or categories (if provided) and those associated with the product.

Occurrence: Conditional

aspects.aspectHelpTextstringReturned only if this field is populated. This provides information and context for the product aspect. The help text can be presented to the seller to clarify the intended purpose of the 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 constraints for this product aspect, including data type and format, input mode, and occurrence.

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.droppablebooleanA value of true indicates that this product aspect can be removed from the specified catalog product definition by omitting it from a product change request. A value of false indicates that this product aspect cannot be dropped (although it is possible that its value could be modified).

Occurrence: Always

aspects.namestringThe name of the product aspect, such as Model Number, Size, or Color.

Occurrence: Always

aspects.valuesarray of ProductAspectValueNot returned if the value of the constraint field is FREE_TEXT and there are no stored values for this aspect. Contains information about the supported values for the product aspect identified by the name field, as well as constraint information for the product aspect values.

These values can be used instead of the product aspect value(s) currently defined for the eBay Catalog product, and those specified in the valuesAssociatedWithProduct array.

Occurrence: Conditional

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

Note that one of these values can possibly be used instead of the product aspect value(s) currently defined for the eBay Catalog product and specified in the aspects.valuesAssociatedWithProduct array.

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.

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

aspects.valuesAssociatedWithProductarray of stringThe value(s) currently defined for the eBay Catalog product for the product aspect identified by the corresponding name field.

Occurrence: Conditional

brandProductIdentifierForProductMetadataContains information about available brand names, their input requirements, and their constraints for the specified product and 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.valueAssociatedWithProductstringThe identifier value currently associated with the product.

Occurrence: Conditional

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

Occurrence: Conditional

eanProductIdentifierForProductMetadataThe 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.valueAssociatedWithProductstringThe identifier value currently associated with the product.

Occurrence: Conditional

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

Occurrence: Conditional

isbnProductIdentifierForProductMetadataThe 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.valueAssociatedWithProductstringThe identifier value currently associated with the product.

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

upcProductIdentifierForProductMetadataThe 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.
75042API_CATALOGREQUESTMissing query param ePID.
75043API_CATALOGREQUESTThe specified ePID is invalid.
75044API_CATALOGREQUESTThe field Primary category Id is required when Other Applicable Category Ids is present.
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 Product Metadata

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

Input

The input is the epid URI parameter, which specifies the ePID of the product (initially returned by the search call in the productSummaries.epid field), and the primary and additional category IDs. There is no payload with this request.
GET
https://api.ebay.com/commerce/catalog/v1_beta/get_product_metadata?epid=241827861&primary_category_id=9355&other_applicable_category_ids=15032,42428

Output

The aspect details are returned in the aspects container for the corresponding product titled "Apple iPhone X," as well as for categories 9355, 15032, and 42428. These aspects are combined into a single array (with duplicates removed) without reference to the product or categories.