Product Type Definitions API v2020-09-01 Use Case Guide
Programmatically access product type attribute and data requirements in the Amazon catalog.
API Version: 2020-09-01
What is the Product Type Definitions API?
Using the Selling Partner API for Product Type Definitions (Product Type Definitions API), you can search and retrieve Amazon Product Type Definitions. Amazon Product Type Definitions describe the attribute and data requirements for items in the Amazon catalog using JSON Schema.
For more details on the JSON Schema format provided by the Product Type Definitions API, refer to the accompanying Amazon Product Type Definition Meta-Schema (v1) documentation.
Refer to the Product Type Definitions API v2020-09-01 Reference for details about API operations and associated data types and schemas.
Key features
-
JSON Schemas: The Product Type Definitions API provides JSON Schemas that describe the seller-agnostic requirements for a given Amazon product type. This includes the data format, attribute constraints (such as required, length, and maximum), and conditionally applied attribute constraints (such as if batteries are included and what type of battery).
-
Compatible with Open-Source Libraries: The JSON Schemas provided can be used with widely available open-source and commercial libraries, applications, and services to understand data requirements, create data mappings, generate user interfaces, and validate listings data before submission to Amazon.
-
Localized presentation details: The JSON Schemas provided include display labels and descriptions for attributes in any supported locale for any marketplace.
-
Product Type Recommendations: The Product Type Definitions API provides recommendations to help you pick the most applicable product type. These recommendations are based on Product Titles in any supported locale for any marketplace, if available.
Terminology
-
JSON Schema: JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. Refer to json-schema.org for more details.
-
Meta Schema: Meta schemas describe the vocabulary used by JSON Schema documents. For example, Amazon product type schemas include vocabulary for
selectors
andeditable
. This vocabulary is described in a meta schema, enabling libraries and applications to understand and validate JSON data based on these extensions to the standard JSON Schema vocabulary. -
Product type: An Amazon product type is a hierarchical categorization of items in the Amazon catalog. Item data requirements are tied to the associated product type of the item.
Tutorial: Search available Product Type Definitions
Use this tutorial to search and identify Amazon product types available in the Product Type Definitions API for a given Amazon marketplace and type of selling partner account.
Prerequisites
To complete this tutorial, you will need:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
Approval for the Product Listing role in your developer profile.
-
The Product Listing role selected in the App registration page for your application.
Search Product Type Definitions
Call the searchDefinitionsProductTypes
operation to search product types available in the Product Type Definitions API.
Request Parameters
Parameter | Example | Description | Required |
---|---|---|---|
marketplaceIds |
ATVPDKIKX0DER |
A comma-delimited list of Amazon marketplace identifiers for the request. Refer to Marketplace IDs for the list of Amazon marketplace identifiers. |
Yes |
keywords |
LUGGAGE |
A comma-delimited list of keywords to search product types by. Default: When no keywords or itemName are provided, the complete list of available product types is provided. |
No |
locale |
en_US |
The locale for the display names in the response. Default: Primary locale of the marketplace. |
No |
searchLocale |
en_US |
The language used for keywords or itemName parameters.Default: Primary locale of the marketplace. |
No |
Request example
GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes
?marketplaceIds=ATVPDKIKX0DER
&keywords=LUGGAGE
&locale=en_US
&searchLocale=en_US
Response
A successful response includes the following:
Name | Example | Description |
---|---|---|
productTypes |
Refer to the Response example | List of product types that match the search request. |
name |
LUGGAGE |
Name of the Amazon product type. |
displayName |
Luggage |
The human-readable and localized description of the Amazon product type. |
marketplaceIds |
ATVPDKIKX0DER |
List of Amazon marketplace identifiers for which the product type is available (within the requested marketplace identifiers). |
productTypeVersion |
UHqSqmb4FNUk= |
The version details for the Amazon product type.. |
Response example
{
"productTypes": [
{
"name": "LUGGAGE",
"displayName": "Luggage",
"marketplaceIds": [
"ATVPDKIKX0DER"
]
}
],
"productTypeVersion": "UHqSqmb4FNUk="
}
Tutorial: Get Product Type Definition recommendations
Use this tutorial to get Amazon product type recommendations from the Product Type Definitions API for a given Amazon marketplace, type of selling partner account, and item name.
Prerequisites
To complete this tutorial, you will need:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
Approval for the Product Listing role in your developer profile.
-
The Product Listing role selected in the App registration page for your application.
Search Product Type Definitions
Call the searchDefinitionsProductTypes
operation to get product type recommendations based on the itemName
from the Product Type Definitions API.
Request Parameters
Parameter | Example | Description | Required |
---|---|---|---|
marketplaceIds |
ATVPDKIKX0DER |
A comma-delimited list of Amazon marketplace identifiers for the request. Refer to Marketplace IDs for the list of Amazon marketplace identifiers. |
Yes |
itemName |
Softside Luggage with Spinner Wheels, Black |
The title of the ASIN to get the product type recommendation. Default: When no keywords or itemName are provided, the complete list of available product types is provided. |
No |
locale |
en_US |
The locale for the display names in the response. Default: Primary locale of the marketplace. |
No |
searchLocale |
en_US |
The language used for the keywords or itemName parameters.Default: Primary locale of the marketplace. |
No |
Request example
GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes
?marketplaceIds=ATVPDKIKX0DER
&itemName=Softside%20Luggage%20with%20Spinner%20Wheels%2C%20Black,
&locale=en_US
&searchLocale=en_US
Response
A successful response includes the following:
Name | Example | Description |
---|---|---|
productTypes |
Refer to the example response | List of product types that match the search request. |
name |
LUGGAGE |
Name of the Amazon product type. |
displayName |
Luggage |
The human-readable and localized description of the Amazon product type. |
marketplaceIds |
ATVPDKIKX0DER |
List of Amazon marketplace identifiers for which the product type is available (within the requested marketplace identifiers). |
productTypeVersion |
UHqSqmb4FNUk= |
The version details for the Amazon product type. |
Response example
{
"productTypes": [
{
"name": "LUGGAGE",
"displayName": "Luggage",
"marketplaceIds": [
"ATVPDKIKX0DER"
]
}
],
"productTypeVersion": "UHqSqmb4FNUk="
}
Tutorial: Retrieve a Product Type Definition
Use this tutorial to return Amazon Product Type Definitions and related schemas from the Product Type Definitions API for a given selling partner, Amazon product type, and Amazon marketplace.
Prerequisites
To complete this tutorial, you will need:
-
Authorization from the Selling Partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
Approval for the Product Listing role in your developer profile.
-
The Product Listing role selected in the App registration page for your application.
Retrieve the Product Type Definition
Call the getDefinitionsProductType
operation to retrieve an Amazon Product Type Definition from the Product Type Definitions API.
Request Parameters
Path Parameters
Parameter | Example | Description | Required |
---|---|---|---|
productType |
LUGGAGE |
Name of the Amazon product type. Type: string |
Yes |
Query Parameters
Parameter | Example | Description | Required |
---|---|---|---|
sellerId |
AXXXXXXXXXXXXX |
The 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. Type: string |
No |
marketplaceIds |
ATVPDKIKX0DER |
Comma-delimited list of Amazon marketplace identifiers. Note: This parameter is limited to one marketplaceId at this time. Refer to Marketplace IDs for the list of Amazon marketplace identifiers. Type: < string > array(csv) |
Yes |
productTypeVersion |
U1d1eorqMs3U= |
Version of the Amazon Product Type Definition to retrieve. 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.Default: LATEST Type: string |
No |
requirements |
LISTING |
Name of the requirements set to retrieve requirements for.
LISTING Type: enum ( |
No |
requirementsEnforced |
ENFORCED |
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 required attributes being present (such as for partial updates).
ENFORCED Type: enum ( |
No |
locale |
en_US |
Locale to retrieve presentation details (labels and descriptions) for. Defaults to the primary locale of the Amazon marketplace.
Default: Type: enum ( |
No |
Request example
GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/LUGGAGE
?marketplaceIds=ATVPDKIKX0DER
&requirements=LISTING
&locale=en_US
Response
A successful response includes the following:
Name | Example | Description |
---|---|---|
metaSchema |
"metaSchema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "QFQDmPwMARO7vwMEyLhOtw==" } |
Link to retrieve the Amazon Product Type Definition Meta-Schema document (valid for seven days). Checksum provided for comparison with previously retrieved documents. Type: |
schema |
"schema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "TBr8ubaxXrUyay9hmxUXUw==" } |
Link to retrieve the JSON Schema document for the Amazon Product Type Definition (valid for seven days). Checksum provided for comparison with previously retrieved documents. Type: |
requirements |
LISTING |
Name of the requirements set the Amazon Product Type Definition applies to.
LISTING Type: enum ( |
requirementsEnforced |
ENFORCED |
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 required attributes being present (such as for partial updates).
ENFORCED Type: enum ( |
propertyGroups |
"propertyGroups": { "offer": { "title": "Offer", "description": "Product Offer", "propertyNames": [ "purchasable_offer" ] } } |
Property groups define logical segmentations of properties described in the Amazon Product Type Definition JSON Schema document. The segmentations can be used for grouping properties in user interfaces, identifying purpose, and so forth. Property groups are informational only and do not impact the structure or formatting of data. Type: < string, |
locale |
en_US |
The locale of the presentation details (labels and descriptions) provided in the Amazon Product Type Definition JSON Schema document. Type: enum ( |
marketplaceIds |
ATVPDKIKX0DER |
Amazon marketplace identifiers for which the Amazon Product Type Definition is applicable. Type: < string > array |
productType |
LUGGAGE |
The name of the Amazon product type that this Product Type Definition applies to. Type: string |
productTypeVersion |
U8L4z4Ud95N16tZlR7rsmbQ== |
Version of the Amazon Product Type Definition. Type: ( |
displayName |
Luggage |
The human-readable and localized description of the Amazon product type. |
Response example
{
"metaSchema": {
"link": {
"resource": "https://...",
"verb": "GET"
},
"checksum": "QFQDmPwMARO7vwMEyLhOtw=="
},
"schema": {
"link": {
"resource": "https://...",
"verb": "GET"
},
"checksum": "TBr8ubaxXrUyay9hmxUXUw=="
},
"requirements": "LISTING",
"requirementsEnforced": "ENFORCED",
"propertyGroups": {
"offer": {
"title": "Offer",
"description": "Product Offer",
"propertyNames": [
"fulfillment_channel_availability",
"purchasable_offer",
"condition_type",
"condition_note",
"list_price",
"product_tax_code",
"merchant_release_date",
"merchant_shipping_group",
"max_order_quantity",
"gift_options",
"main_offer_image_locator",
"other_offer_image_locator_1",
"other_offer_image_locator_2",
"other_offer_image_locator_3",
"other_offer_image_locator_4",
"other_offer_image_locator_5"
]
},
"images": {
"title": "Images",
"description": "Physical images or URL's",
"propertyNames": [
"main_product_image_locator",
"other_product_image_locator_1",
"other_product_image_locator_2",
"other_product_image_locator_3",
"other_product_image_locator_4",
"other_product_image_locator_5",
"other_product_image_locator_6",
"other_product_image_locator_7",
"other_product_image_locator_8",
"swatch_product_image_locator"
]
},
"shipping": {
"title": "Shipping",
"description": "Information to determine shipping and storage of your product (e.g., package dimensions, weight, volume)",
"propertyNames": [
"item_dimensions",
"item_package_dimensions",
"item_package_weight"
]
},
"variations": {
"title": "Variations",
"description": "Variations that product will use",
"propertyNames": [
"parentage_level",
"child_parent_sku_relationship",
"variation_theme"
]
},
"safety_and_compliance": {
"title": "Safety & Compliance",
"description": "Information to indicate product compliance, hazardous materials, and legal and safety warnings (e.g., lithium batteries, choking hazards, Consumer Product Safety Information Act (CPSIA))",
"propertyNames": [
"country_of_origin",
"warranty_description",
"batteries_required",
"batteries_included",
"battery",
"num_batteries",
"number_of_lithium_metal_cells",
"number_of_lithium_ion_cells",
"lithium_battery",
"supplier_declared_dg_hz_regulation",
"hazmat",
"safety_data_sheet_url",
"item_weight",
"ghs",
"supplier_declared_material_regulation",
"california_proposition_65",
"pesticide_marking"
]
},
"product_identity": {
"title": "Product Identity",
"description": "Information to uniquely identify your product (e.g., UPC, EAN, GTIN, Product Type, Brand)",
"propertyNames": [
"item_name",
"brand",
"supplier_declared_has_product_identifier_exemption",
"externally_assigned_product_identifier",
"merchant_suggested_asin",
"item_type_keyword",
"item_type_name",
"model_number",
"manufacturer"
]
},
"product_details": {
"title": "Product Details",
"description": "Information and characteristics to describe the product to support search, browse and detail page content (e.g., bullets, product features, model, style name)",
"propertyNames": [
"product_description",
"bullet_point",
"generic_keyword",
"special_feature",
"style",
"department",
"target_gender",
"age_range_description",
"material",
"outer",
"fabric_type",
"lining_description",
"number_of_items",
"number_of_wheels",
"wheel",
"model_name",
"color",
"size",
"size_map",
"part_number",
"compliance_media"
]
}
},
"locale": "en_US",
"marketplaceIds": [
"ATVPDKIKX0DER"
],
"productType": "LUGGAGE",
"displayName": "Luggage",
"productTypeVersion": {
"version": "U8L4z4Ud95N16tZlR7rsmbQ==",
"latest": true,
"releaseCandidate": false
}
}
Retrieve the schema documents
In the previous step, the retrieved Amazon Product Type Definition includes details about the Amazon product type and links to retrieve the meta schema and product type schema documents. The links provided are valid for seven days.
Schema documents can be retrieved programmatically with a standard HTTP client or manually with a web browser.
Meta scheme names cannot be resolved via the web
The Amazon Product Type Definition JSON Schema document references the meta schema by name. Some JSON Schema libraries attempt to resolve meta schema names online via the web, which the Amazon Product Type Definition Meta-Schema (v1) does not support. These libraries should be configured to use a downloaded copy of the meta schema instead. Refer to the accompanying Amazon Product Type Definition Meta-Schema (v1) documentation for more details.
Frequently Asked Questions
This documentation covers common questions and details for the Product Type Definitions API. For questions or concerns not covered by this documentation, contact Selling Partner API support or create an issue on the GitHub repository.
How fresh are Amazon Product Type Definitions?
Unless specifying a previous productTypeVersion
, the Amazon Product Type Definitions always describe the latest up-to-date Amazon catalog requirements.
Are all Amazon product types available with the Product Type Definitions API?
No. Amazon is continually expanding support for new and existing Amazon product types in the Product Type Definitions API. For the up-to-date list of available Amazon product types, use the Product Type Definitions API.
What version of JSON Schema is used?
Amazon Product Type Definition JSON Schemas extend JSON Schema 2019-09. Refer to the accompanying Amazon Product Type Definition Meta-Schema (v1) documentation for more details.
How will future versions of JSON Schema be Leveraged?
As future versions of JSON Schema are adopted by the Product Type Definitions API, they will be accompanied by a new version release of the Product Type Definitions API and Amazon Product Type Definition Meta-Schema.
Future versions of JSON Schema will not be adopted by existing versions of the Product Type Definitions API or Amazon Product Type Definition Meta-Schema.
Do Product Type Definition JSON Schemas include custom vocabulary?
Most Amazon catalog requirements are described utilizing standard JSON Schema 2019-09 vocabulary. However, there are a few requirements that necessitate extending JSON Schema with custom vocabulary. Refer to the accompanying Amazon Product Type Definition Meta-Schema (v1) documentation for more details.
Am I required to implement validation for custom vocabulary?
No. The Amazon Product Type Definition Meta-Schema (v1) uses custom vocabulary to fully describe Amazon catalog requirements. Validating data with custom data enables you to prevent most listings-related issues from occurring before submitting to Amazon. However, it is up-to-you to implement such validation. Without implementing this validation, submitting data to Amazon can produce listings-related issues after submission to Amazon.
Do I need custom code to use JSON Schemas?
Yes. The amount of custom code depends upon your application. Example scenarios:
-
Using Open-Source Library with Validation of Custom Vocabulary: Leveraging an open-source library to handle most JSON Schema validation means custom code is necessary to retrieve schemas from the Product Type Definitions API, to implement validation of custom vocabulary, and to integrate with the open-source library.
-
Using Open-Source Library without Validation of Custom Vocabulary: Leveraging an open-source library to handle most JSON Schema validation means custom code is necessary to retrieve schemas from the Product Type Definitions API and to integrate with the open-source library.
What Open-Source Libraries are Available?
Dozens of open-source libraries and implementations are available to validate data, render user interfaces, and generate code. Refer to JSON Schema Tooling for a full list.
Amazon does not directly support or endorse any specific open-source or commercial libraries and implementations. Examples provided in this documentation are for reference only.
What examples are available for validating data with product type schemas?
The accompanying Amazon Product Type Definition Meta-Schema (v1) documentation includes example integrations with open-source libraries to validate data with custom vocabulary in .NET (C#), Java, and JavaScript (Node.js).
How do I report issues with Amazon Product Type Definitions?
For issues specific to the Product Type Definitions API or the content of Amazon Product Type Definition JSON Schemas, contact Selling Partner API support.
Updated 2 days ago