Product Type Definitions API v2020-09-01 Use Case Guide

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 schemas.

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.

To learn more about the terms that are used on this page, refer to Terminology.

⭐

Tip

Unless you specify a previous productTypeVersion, the Amazon Product Type Definitions always describe the latest up-to-date Amazon catalog requirements.

JSON schema support

Amazon Product Type Definition JSON schemas extend JSON Schema 2019-09. If future versions of JSON Schema are adopted by the Product Type Definitions API, they will be accompanied by a new Product Type Definitions API version release and Amazon Product Type Definition Meta-Schema.

Most Amazon catalog requirements use standard JSON Schema 2019-09 vocabulary. The Amazon Product Type Definition Meta-Schema also uses custom vocabulary to fully describe Amazon catalog requirements. Custom vocabulary data validation is recommended but not required.

Validating data with custom data prevents most listings-related issues from occurring before submitting to Amazon. However, it is up to you to implement such validation.

The amount of custom code required depends on your application. Refer to the following JSON schema validation use cases for examples of when custom code is needed:

• Open-source library with validation of custom vocabulary

  • Retrieve schemas from the Product Type Definitions API
  • Implement validation of custom vocabulary
  • Integrate with the open-source library

• Open-source library without validation of custom vocabulary

  • Retrieve schemas from the Product Type Definitions API
  • Integrate with the open-source library

For more information, refer to the Amazon Product Type Definition Meta-Schema (v1) documentation, which includes example integrations with open-source libraries to validate data with a custom vocabulary in .NET (C#), Java, and JavaScript (Node.js).

Open-source libraries

There are dozens of open-source libraries and implementations available to validate data, render user interfaces, and generate code. For a complete list, refer to JSON Schema Tooling.

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.

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

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

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

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.