Overview

The Selling Partner API for Catalog Items provides programmatic access to information about items in the Amazon catalog.

For more information, see the Catalog Items API Use Case Guide (opens new window).

Version information

Version : 2020-12-01

Operations

searchCatalogItems
getCatalogItem

Paths

searchCatalogItems

GET /catalog/2020-12-01/items

Description

Search for and return a list of Amazon catalog items and associated information.

Usage Plans:

Plan type	Rate (requests per second)	Burst
Default	5	5
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
Query	keywords required	A comma-delimited list of words or item identifiers to search the Amazon catalog for.	< string > array(csv)	-
Query	marketplaceIds required	A comma-delimited list of Amazon marketplace identifiers for the request. Max count : 1	< string > array(csv)	-
Query	includedData optional	A comma-delimited list of data sets to include in the response. Default: summaries.	< enum (IncludedData) > array(csv)	-
Query	brandNames optional	A comma-delimited list of brand names to limit the search to.	< string > array(csv)	-
Query	classificationIds optional	A comma-delimited list of classification identifiers to limit the search to.	< string > array(csv)	-
Query	pageSize optional	Number of results to be returned per page. Maximum : 20	integer	10
Query	pageToken optional	A token to fetch a certain page when there are multiple pages worth of results.	string	-
Query	keywordsLocale optional	The language the keywords are provided in. Defaults to the primary locale of the marketplace.	string	-
Query	locale optional	Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace.	string	-

Responses

HTTP Code	Description	Schema
200	Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier.	ItemSearchResults

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

Consumes

• application/json

Produces

• application/json

getCatalogItem

GET /catalog/2020-12-01/items/{asin}

Description

Retrieves details for an item in the Amazon catalog.

Usage Plans:

Plan type	Rate (requests per second)	Burst
Default	5	5
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
Path	asin required	The Amazon Standard Identification Number (ASIN) of the item.	string
Query	marketplaceIds required	A comma-delimited list of Amazon marketplace identifiers. Data sets in the response contain data only for the specified marketplaces.	< string > array(csv)
Query	includedData optional	A comma-delimited list of data sets to include in the response. Default: summaries.	< enum (IncludedData) > array(csv)
Query	locale optional	Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace.	string

Responses

HTTP Code	Description	Schema
200	Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier.	Item

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

Item

An item in the Amazon catalog.

Name	Description	Schema
asin required	Amazon Standard Identification Number (ASIN) is the unique identifier for an item in the Amazon catalog.	ItemAsin
attributes optional	A JSON object that contains structured item attribute data keyed by attribute name. Catalog item attributes are available only to brand owners and conform to the related product type definitions available in the Selling Partner API for Product Type Definitions.	ItemAttributes
identifiers optional	Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.	ItemIdentifiers
images optional	Images for an item in the Amazon catalog. All image variants are provided to brand owners. Otherwise, a thumbnail of the "MAIN" image variant is provided.	ItemImages
productTypes optional	Product types associated with the Amazon catalog item.	ItemProductTypes
salesRanks optional	Sales ranks of an Amazon catalog item.	ItemSalesRanks
summaries optional	Summary details of an Amazon catalog item.	ItemSummaries
variations optional	Variation details by marketplace for an Amazon catalog item (variation relationships).	ItemVariations
vendorDetails optional	Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only.	ItemVendorDetails

ItemAsin

Amazon Standard Identification Number (ASIN) is the unique identifier for an item in the Amazon catalog.

Type : string

ItemAttributes

A JSON object that contains structured item attribute data keyed by attribute name. Catalog item attributes are available only to brand owners and conform to the related product type definitions available in the Selling Partner API for Product Type Definitions.

Type : object

ItemIdentifiers

Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.

Type : < ItemIdentifiersByMarketplace > array

ItemIdentifiersByMarketplace

Identifiers associated with the item in the Amazon catalog for the indicated Amazon marketplace.

Name	Description	Schema
marketplaceId required	Amazon marketplace identifier.	string
identifiers required	Identifiers associated with the item in the Amazon catalog for the indicated Amazon marketplace.	< ItemIdentifier > array

ItemIdentifier

Identifier associated with the item in the Amazon catalog, such as a UPC or EAN identifier.

Name	Description	Schema
identifierType required	Type of identifier, such as UPC, EAN, or ISBN.	string
identifier required	Identifier.	string

ItemImages

Images for an item in the Amazon catalog. All image variants are provided to brand owners. Otherwise, a thumbnail of the "MAIN" image variant is provided.

Type : < ItemImagesByMarketplace > array

ItemImagesByMarketplace

Images for an item in the Amazon catalog for the indicated Amazon marketplace.

Name	Description	Schema
marketplaceId required	Amazon marketplace identifier.	string
images required	Images for an item in the Amazon catalog for the indicated Amazon marketplace.	< ItemImage > array

ItemImage

Image for an item in the Amazon catalog.

Name	Description	Schema
variant required	Variant of the image, such as MAIN or PT01. Example : "MAIN"	enum (Variant)
link required	Link, or URL, for the image.	string
height required	Height of the image in pixels.	integer
width required	Width of the image in pixels.	integer

ItemProductTypes

Product types associated with the Amazon catalog item.

Type : < ItemProductTypeByMarketplace > array

ItemProductTypeByMarketplace

Product type associated with the Amazon catalog item for the indicated Amazon marketplace.

Name	Description	Schema
marketplaceId optional	Amazon marketplace identifier.	string
productType optional	Name of the product type associated with the Amazon catalog item. Example : "LUGGAGE"	string

ItemSalesRanks

Sales ranks of an Amazon catalog item.

Type : < ItemSalesRanksByMarketplace > array

ItemSalesRanksByMarketplace

Sales ranks of an Amazon catalog item for the indicated Amazon marketplace.

Name	Description	Schema
marketplaceId required	Amazon marketplace identifier.	string
ranks required	Sales ranks of an Amazon catalog item for an Amazon marketplace.	< ItemSalesRank > array

ItemSalesRank

Sales rank of an Amazon catalog item.

Name	Description	Schema
title required	Title, or name, of the sales rank.	string
link optional	Corresponding Amazon retail website link, or URL, for the sales rank.	string
rank required	Sales rank value.	integer

ItemSummaries

Summary details of an Amazon catalog item.

Type : < ItemSummaryByMarketplace > array

ItemSummaryByMarketplace

Summary details of an Amazon catalog item for the indicated Amazon marketplace.

Name	Description	Schema
marketplaceId required	Amazon marketplace identifier.	string
brandName optional	Name of the brand associated with an Amazon catalog item.	string
browseNode optional	Identifier of the browse node associated with an Amazon catalog item.	string
colorName optional	Name of the color associated with an Amazon catalog item.	string
itemName optional	Name, or title, associated with an Amazon catalog item.	string
manufacturer optional	Name of the manufacturer associated with an Amazon catalog item.	string
modelNumber optional	Model number associated with an Amazon catalog item.	string
sizeName optional	Name of the size associated with an Amazon catalog item.	string
styleName optional	Name of the style associated with an Amazon catalog item.	string

ItemVariations

Variation details by marketplace for an Amazon catalog item (variation relationships).

Type : < ItemVariationsByMarketplace > array

ItemVariationsByMarketplace

Variation details for the Amazon catalog item for the indicated Amazon marketplace.

Name	Description	Schema
marketplaceId required	Amazon marketplace identifier.	string
asins required	Identifiers (ASINs) of the related items.	< string > array
variationType required	Type of variation relationship of the Amazon catalog item in the request to the related item(s): "PARENT" or "CHILD". Example : "PARENT"	enum (VariationType)

ItemVendorDetails

Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only.

Type : < ItemVendorDetailsByMarketplace > array

ItemVendorDetailsByMarketplace

Vendor details associated with an Amazon catalog item for the indicated Amazon marketplace.

Name	Description	Schema
marketplaceId required	Amazon marketplace identifier.	string
brandCode optional	Brand code associated with an Amazon catalog item.	string
categoryCode optional	Product category associated with an Amazon catalog item.	string
manufacturerCode optional	Manufacturer code associated with an Amazon catalog item.	string
manufacturerCodeParent optional	Parent vendor code of the manufacturer code.	string
productGroup optional	Product group associated with an Amazon catalog item.	string
replenishmentCategory optional	Replenishment category associated with an Amazon catalog item.	enum (ReplenishmentCategory)
subcategoryCode optional	Product subcategory associated with an Amazon catalog item.	string

ItemSearchResults

Items in the Amazon catalog and search related metadata.

Name	Description	Schema
numberOfResults required	The estimated total number of products matched by the search query (only results up to the page count limit will be returned per request regardless of the number found). Note: The maximum number of items (ASINs) that can be returned and paged through is 1000.	integer
pagination required	If available, the nextToken and/or previousToken values required to return paginated results.	Pagination
refinements required	Search refinements.	Refinements
items required	A list of items from the Amazon catalog.	< Item > array

Pagination

When a request produces a response that exceeds the pageSize, pagination occurs. This means the response is divided into individual pages. To retrieve the next page or the previous page, you must pass the nextToken value or the previousToken value as the pageToken parameter in the next request. When you receive the last page, there will be no nextToken key in the pagination object.

Name	Description	Schema
nextToken optional	A token that can be used to fetch the next page.	string
previousToken optional	A token that can be used to fetch the previous page.	string

Refinements

Search refinements.

Name	Description	Schema
brands required	Brand search refinements.	< BrandRefinement > array
classifications required	Classification search refinements.	< ClassificationRefinement > array

BrandRefinement

Description of a brand that can be used to get more fine-grained search results.

Name	Description	Schema
numberOfResults required	The estimated number of results that would still be returned if refinement key applied.	integer
brandName required	Brand name. For display and can be used as a search refinement.	string

ClassificationRefinement

Description of a classification that can be used to get more fine-grained search results.

Name	Description	Schema
numberOfResults required	The estimated number of results that would still be returned if refinement key applied.	integer
displayName required	Display name for the classification.	string
classificationId required	Identifier for the classification that can be used for search refinement purposes.	string

Variant

Variant of the image, such as MAIN or PT01.

Type : enum

Value	Description
MAIN	Main image for the item.
PT01	Other image #1 for the item.
PT02	Other image #2 for the item.
PT03	Other image #3 for the item.
PT04	Other image #4 for the item.
PT05	Other image #5 for the item.
PT06	Other image #6 for the item.
PT07	Other image #7 for the item.
PT08	Other image #8 for the item.
SWCH	Swatch image for the item.

VariationType

Type of variation relationship of the Amazon catalog item in the request to the related item(s): "PARENT" or "CHILD".

Type : enum

Value	Description
PARENT	The Amazon catalog item in the request is a variation parent of the related item(s) indicated by ASIN.
CHILD	The Amazon catalog item in the request is a variation child of the related item identified by ASIN.

ReplenishmentCategory

Replenishment category associated with an Amazon catalog item.

Type : enum

Value	Description
ALLOCATED	Indicates non-automated purchasing of inventory that has been allocated to Amazon by the vendor.
BASIC_REPLENISHMENT	Indicates non-automated purchasing of inventory.
IN_SEASON	Indicates non-automated purchasing of inventory for seasonal items.
LIMITED_REPLENISHMENT	Holding queue replenishment status before an item is NEW_PRODUCT.
MANUFACTURER_OUT_OF_STOCK	Indicates vendor is out of stock for a longer period of time and cannot backorder.
NEW_PRODUCT	Indicates a new item that Amazon does not yet stock in inventory.
NON_REPLENISHABLE	Indicates assortment parent used for detail page display, not actual items.
NON_STOCKUPABLE	Indicates drop ship inventory that Amazon does not stock in its fulfillment centers.
OBSOLETE	Indicates item is obsolete and should not be ordered.
PLANNED_REPLENISHMENT	Indicates active items that should be automatically ordered.

IncludedData

Type : enum

For use with the operation(s): searchCatalogItems

Value	Description
identifiers	Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.
images	Images for an item in the Amazon catalog. All image variants are provided to brand owners; a thumbnail of the "MAIN" image variant is provided otherwise.
productTypes	Product types associated with the Amazon catalog item.
salesRanks	Sales ranks of an Amazon catalog item.
summaries	Summary details of an Amazon catalog item.
variations	Variation details of an Amazon catalog item (variation relationships).
vendorDetails	Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only.

For use with the operation(s): getCatalogItem

Value	Description
attributes	A JSON object containing structured item attribute data keyed by attribute name. Catalog item attributes are available only to brand owners and conform to the related Amazon product type definitions available in the Selling Partner API for Product Type Definitions.
identifiers	Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.
images	Images for an item in the Amazon catalog. All image variants are provided to brand owners. Otherwise, a thumbnail of the "MAIN" image variant is provided.
productTypes	Product types associated with the Amazon catalog item.
salesRanks	Sales ranks of an Amazon catalog item.
summaries	Summary details of an Amazon catalog item.
variations	Variation details of an Amazon catalog item (variation relationships).
vendorDetails	Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only.