Product Type Definitions API v2020-09-01 reference

AmazonSPAPI

# 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 (opens new window).

# Version information

Version : 2020-09-01

# Operations

searchDefinitionsProductTypes
getDefinitionsProductType

# Paths

# searchDefinitionsProductTypes

GET /definitions/2020-09-01/productTypes

# Description

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

Usage Plans:

Plan type Rate (requests per second) Burst
Default 5 10
Selling partner specific Variable Variable

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 (opens new window).

# Parameters

Type Name Description Schema
Query keywords
optional
A comma-delimited list of keywords to search product types by. < string > array(csv)
Query marketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers for the request. < string > array(csv)

# Responses

HTTP Code Description Schema
200 Successfully 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
429 The 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

# getDefinitionsProductType

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

# Description

Retrieve an Amazon product type definition.

Usage Plans:

Plan type Rate (requests per second) Burst
Default 5 10
Selling partner specific Variable Variable

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 (opens new window).

# Parameters

Type Name Description Schema Default
Path productType
required
The Amazon product type name. string -
Query sellerId
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 -
Query marketplaceIds
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) -
Query productTypeVersion
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"
Query requirements
optional
The name of the requirements set to retrieve requirements for. enum (Requirements) "LISTING"
Query requirementsEnforced
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"
Query locale
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 Code Description Schema
200 Successfully 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
429 The 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 Code Description Schema
400 Request 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
403 Indicates 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
404 The 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
413 The 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
415 The 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
500 An 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
503 Temporary 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.

Name Description Schema
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.

Name Schema
errors
required
< Error > array

Name Description Schema
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

Name Description Schema
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.

Name Description Schema
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.

Name Description Schema
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.

Name Description Schema
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.

Name Description Schema
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.

Name Schema
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

Value Description
DEFAULT Default locale of the requested Amazon marketplace.
ar Arabic
ar_AE Arabic (U.A.E.)
de German
de_DE German (Germany)
en English
en_AE English (U.A.E.)
en_AU English (Australia)
en_CA English (Canada)
en_GB English (United Kingdom)
en_IN English (India)
en_SG English (Singapore)
en_US English (United States)
es Spanish
es_ES Spanish (Spain)
es_MX Spanish (Mexico)
es_US Spanish (United States)
fr French
fr_CA French (Canada)
fr_FR French (France)
it Italian
it_IT Italian (Italy)
ja Japanese
ja_JP Japanese (Japan)
nl Dutch
nl_NL Dutch (Netherlands)
pl Polish
pl_PL Polish (Poland)
pt Portuguese
pt_BR Portuguese (Brazil)
pt_PT Portuguese (Portugal)
sv Swedish
sv_SE Swedish (Sweden)
tr Turkish
tr_TR Turkish (Turkey)
zh Chinese
zh_CN Chinese (Simplified)
zh_TW Chinese (Traditional)

# Verb

HTTP method for the link operation.

Type : enum

Value Description
GET The 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).

Value Description
ENFORCED Schema enforces required and conditionally required attributes (used for full payload validation).
NOT_ENFORCED Schema 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).

Value Description
ENFORCED Request schema with required and conditionally required attributes enforced (used for full payload validation).
NOT_ENFORCED Request 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.

Value Description
LISTING Indicates the schema contains product facts and sales terms.
LISTING_PRODUCT_ONLY Indicates the schema data contains product facts only.
LISTING_OFFER_ONLY Indicates the schema data contains sales terms only.

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

Value Description
LISTING Request schema containing product facts and sales terms.
LISTING_PRODUCT_ONLY Request schema containing product facts only.
LISTING_OFFER_ONLY Request schema containing sales terms only.
Last Updated: 10/11/2022, 9:45:34 PM