Product Type Definitions API v2020-09-01 reference

Programmatic access to attribute and data requirements for product types in the Amazon catalog.

Overview

The Selling Partner API for Product Type Definitions provides programmatic access to attribute and data requirements for product types in the Amazon catalog. Use this API to return the JSON Schema for a product type that you can then use with other Selling Partner APIs, such as the Selling Partner API for Listings Items, the Selling Partner API for Catalog Items, and the Selling Partner API for Feeds (for JSON-based listing feeds).

For more information, see the Product Type Definitions API Use Case Guide.

Version information

Version : 2020-09-01

Contact information

Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html

License information

License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0

URI scheme

Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Operations

searchDefinitionsProductTypes
getDefinitionsProductType

Paths

GET /definitions/2020-09-01/productTypes

Operation: searchDefinitionsProductTypes

Description

Search for and return a list of Amazon product types that have definitions available.

Usage Plans:

Plan typeRate (requests per second)Burst
Default510
Selling partner specificVariableVariable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
Querykeywords
optional
A comma-delimited list of keywords to search product types by.< string > array(csv)
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers for the request.< string > array(csv)

Responses

HTTP CodeDescriptionSchema
200Successfully retrieved a list of Amazon product types that have definitions available.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
ProductTypeList
429The frequency of requests was greater than allowed.
Headers :
x-amzn-RequestId (string) : Unique request reference identifier.
ErrorList

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Consumes

  • application/json

Produces

  • application/json

GET /definitions/2020-09-01/productTypes/{productType}

Operation: getDefinitionsProductType

Description

Retrieve an Amazon product type definition.

Usage Plans:

Plan typeRate (requests per second)Burst
Default510
Selling partner specificVariableVariable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchemaDefault
PathproductType
required
The Amazon product type name.string-
QuerysellerId
optional
A selling partner identifier. When provided, seller-specific requirements and values are populated within the product type definition schema, such as brand names associated with the selling partner.string-
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers for the request.
Note: This parameter is limited to one marketplaceId at this time.
< string > array(csv)-
QueryproductTypeVersion
optional
The version of the Amazon product type to retrieve. Defaults to "LATEST",. Prerelease versions of product type definitions may be retrieved with "RELEASE_CANDIDATE". If no prerelease version is currently available, the "LATEST" live version will be provided.string"LATEST"
Queryrequirements
optional
The name of the requirements set to retrieve requirements for.enum (Requirements)"LISTING"
QueryrequirementsEnforced
optional
Identifies if the required attributes for a requirements set are enforced by the product type definition schema. Non-enforced requirements enable structural validation of individual attributes without all the required attributes being present (such as for partial updates).enum (RequirementsEnforced)"ENFORCED"
Querylocale
optional
Locale for retrieving display labels and other presentation details. Defaults to the default language of the first marketplace in the request.enum (Locale)"DEFAULT"

Responses

HTTP CodeDescriptionSchema
200Successfully retrieved an Amazon product type definition.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
ProductTypeDefinition
429The frequency of requests was greater than allowed.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
ErrorList

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Consumes

  • application/json

Produces

  • application/json

Error Responses and Schemas

This table contains HTTP status codes and associated information for error responses.

HTTP CodeDescriptionSchema
400Request has missing or invalid parameters and cannot be parsed.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
404The resource specified does not exist.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
413The request size exceeded the maximum accepted size.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
415The request payload is in an unsupported format.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
503Temporary overloading or maintenance of the server.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList

Definitions

Error

Error response returned when the request is unsuccessful.

NameDescriptionSchema
code
required
An error code that identifies the type of error that occurred.string
message
required
A message that describes the error condition.string
details
optional
Additional details that can help the caller understand or fix the issue.string

ErrorList

A list of error responses returned when a request is unsuccessful.

NameSchema
errors
required
< Error > array

SchemaLink

NameDescriptionSchema
link
required
Link to retrieve the schema.link
checksum
required
Checksum hash of the schema (Base64 MD5). Can be used to verify schema contents, identify changes between schema versions, and for caching.string


link

NameDescriptionSchema
resource
required
URI resource for the link.string
verb
required
HTTP method for the link operation.enum (Verb)

ProductTypeDefinition

A product type definition represents the attributes and data requirements for a product type in the Amazon catalog. Product type definitions are used interchangeably between the Selling Partner API for Listings Items, Selling Partner API for Catalog Items, and JSON-based listings feeds in the Selling Partner API for Feeds.

NameDescriptionSchema
metaSchema
optional
Link to meta-schema describing the vocabulary used by the product type schema.SchemaLink
schema
required
Link to schema describing the attributes and requirements for the product type.SchemaLink
requirements
required
Name of the requirements set represented in this product type definition.enum (Requirements)
requirementsEnforced
required
Identifies if the required attributes for a requirements set are enforced by the product type definition schema. Non-enforced requirements enable structural validation of individual attributes without all of the required attributes being present (such as for partial updates).enum (RequirementsEnforced)
propertyGroups
required
Mapping of property group names to property groups. Property groups represent logical groupings of schema properties that can be used for display or informational purposes.< string, PropertyGroup > map
locale
required
Locale of the display elements contained in the product type definition.string
marketplaceIds
required
Amazon marketplace identifiers for which the product type definition is applicable.< string > array
productType
required
The name of the Amazon product type that this product type definition applies to.string
productTypeVersion
required
The version details for the Amazon product type.ProductTypeVersion

PropertyGroup

A property group represents a logical grouping of schema properties that can be used for display or informational purposes.

NameDescriptionSchema
title
optional
The display label of the property group.string
description
optional
The description of the property group.string
propertyNames
optional
The names of the schema properties for the property group.< string > array

ProductTypeVersion

The version details for an Amazon product type.

NameDescriptionSchema
version
required
Version identifier.string
latest
required
When true, the version indicated by the version identifier is the latest available for the Amazon product type.boolean
releaseCandidate
optional
When true, the version indicated by the version identifier is the prerelease (release candidate) for the Amazon product type.boolean

ProductType

An Amazon product type with a definition available.

NameDescriptionSchema
name
required
The name of the Amazon product type.string
marketplaceIds
required
The Amazon marketplace identifiers for which the product type definition is available.< string > array

ProductTypeList

A list of Amazon product types with definitions available.

NameSchema
productTypes
required
< ProductType > array

Locale

Locale for retrieving display labels and other presentation details. Defaults to the default language of the first marketplace in the request.

Type : enum

ValueDescription
DEFAULTDefault locale of the requested Amazon marketplace.
arArabic
ar_AEArabic (U.A.E.)
deGerman
de_DEGerman (Germany)
enEnglish
en_AEEnglish (U.A.E.)
en_AUEnglish (Australia)
en_CAEnglish (Canada)
en_GBEnglish (United Kingdom)
en_INEnglish (India)
en_SGEnglish (Singapore)
en_USEnglish (United States)
esSpanish
es_ESSpanish (Spain)
es_MXSpanish (Mexico)
es_USSpanish (United States)
frFrench
fr_CAFrench (Canada)
fr_FRFrench (France)
itItalian
it_ITItalian (Italy)
jaJapanese
ja_JPJapanese (Japan)
nlDutch
nl_NLDutch (Netherlands)
plPolish
pl_PLPolish (Poland)
ptPortuguese
pt_BRPortuguese (Brazil)
pt_PTPortuguese (Portugal)
svSwedish
sv_SESwedish (Sweden)
trTurkish
tr_TRTurkish (Turkey)
zhChinese
zh_CNChinese (Simplified)
zh_TWChinese (Traditional)

Verb

HTTP method for the link operation.

Type : enum

ValueDescription
GETThe provided resource is accessed with the HTTP GET method.

RequirementsEnforced

Type : enum

For use with the definition(s): ProductTypeDefinition
Identifies if the required attributes for a requirements set are enforced by the product type definition schema. Non-enforced requirements enable structural validation of individual attributes without all of the required attributes being present (such as for partial updates).

ValueDescription
ENFORCEDSchema enforces required and conditionally required attributes (used for full payload validation).
NOT_ENFORCEDSchema does not enforce required and conditionally required attributes (used for partial payload validation, such as for single attributes).

For use with the operation(s): getDefinitionsProductType
Identifies if the required attributes for a requirements set are enforced by the product type definition schema. Non-enforced requirements enable structural validation of individual attributes without all the required attributes being present (such as for partial updates).

ValueDescription
ENFORCEDRequest schema with required and conditionally required attributes enforced (used for full payload validation).
NOT_ENFORCEDRequest schema with required and conditionally required attributes not enforced (used for partial payload validation, such as for single attributes).

Requirements

Type : enum

For use with the definition(s): ProductTypeDefinition
Name of the requirements set represented in this product type definition.

ValueDescription
LISTINGIndicates the schema contains product facts and sales terms.
LISTING_PRODUCT_ONLYIndicates the schema data contains product facts only.
LISTING_OFFER_ONLYIndicates the schema data contains sales terms only.

For use with the operation(s): getDefinitionsProductType
The name of the requirements set to retrieve requirements for.

ValueDescription
LISTINGRequest schema containing product facts and sales terms.
LISTING_PRODUCT_ONLYRequest schema containing product facts only.
LISTING_OFFER_ONLYRequest schema containing sales terms only.

Did this page help you?