HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Catalog Items API v2022-04-01 Reference

Use Catalog Items to gain programmatic access to information contained in the Amazon catalog.

Use the Selling Partner API for Catalog Items to retrieve information about items in the Amazon catalog.

For more information, refer to the Catalog Items API Use Case Guide.

Version information

Version : 2022-04-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

searchCatalogItems
getCatalogItem

Paths

GET /catalog/2022-04-01/items

Operation: searchCatalogItems

Description

Search for a list of Amazon catalog items and item-related information. You can search by identifier or by keywords.

Usage Plan:

Rate (requests per second)Burst
55

The x-amzn-RateLimit-Limit response header contains the usage plan rate limits for the operation, when available. The preceding table contains the default rate and burst values for this operation. Selling partners whose business demands require higher throughput might have higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits.

Parameters

TypeNameDescriptionSchemaDefault
Queryidentifiers
optional
A comma-delimited list of product identifiers that you can use to search the Amazon catalog. Note: You cannot include identifiers and keywords in the same request.
Max count : 20
< string > array(csv)-
QueryidentifiersType
optional
The type of product identifiers that you can use to search the Amazon catalog. Note: identifiersType is required when identifiers is in the request.enum (IdentifiersType)-
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers. To find the ID for your marketplace, refer to Marketplace IDs.
Max count : 1
< string > array(csv)-
QueryincludedData
optional
A comma-delimited list of datasets to include in the response.< enum (IncludedData) > array(csv)summaries
Querylocale
optional
The locale for which you want to retrieve localized summaries. Defaults to the primary locale of the marketplace.string-
QuerysellerId
optional
A selling partner identifier, such as a seller account or vendor code. Note: Required when identifiersType is SKU.string-
Querykeywords
optional
A comma-delimited list of keywords that you can use to search the Amazon catalog. Note: You cannot include keywords and identifiers in the same request.
Max count : 20
< string > array(csv)-
QuerybrandNames
optional
A comma-delimited list of brand names that you can use to limit the search in queries based on keywords. Note: Cannot be used with identifiers.< string > array(csv)-
QueryclassificationIds
optional
A comma-delimited list of classification identifiers that you can use to limit the search in queries based on keywords. Note: Cannot be used with identifiers.< string > array(csv)-
QuerypageSize
optional
The number of results to include on each page.
Maximum : 20
integer10
QuerypageToken
optional
A token that you can use to fetch a specific page when there are multiple pages of results.string-
QuerykeywordsLocale
optional
The language of the keywords that are included in queries based on keywords. Defaults to the primary locale of the marketplace. Note: Cannot be used with identifiers.string-

Responses

HTTP CodeDescriptionSchema
200Success.
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

GET /catalog/2022-04-01/items/{asin}

Operation: getCatalogItem

Description

Retrieves details for an item in the Amazon catalog.

Usage Plan:

Rate (requests per second)Burst
55

The x-amzn-RateLimit-Limit response header contains the usage plan rate limits for the operation, when available. The preceding table contains the default rate and burst values for this operation. Selling partners whose business demands require higher throughput might have higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits.

Parameters

TypeNameDescriptionSchemaDefault
Pathasin
required
The Amazon Standard Identification Number (ASIN) of the item.string-
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers. To find the ID for your marketplace, refer to Marketplace IDs.< string > array(csv)-
QueryincludedData
optional
A comma-delimited list of datasets to include in the response.< enum (IncludedData) > array(csv)summaries
Querylocale
optional
The locale for which you want to retrieve localized summaries. Defaults to the primary locale of the marketplace.string-

Responses

HTTP CodeDescriptionSchema
200Success.
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 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-RequestId (string):Unique request reference identifier.
ErrorList
415The request payload is in an unsupported format.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
429The frequency of requests was greater than allowed.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
503Temporary overloading or maintenance of the server.
Headers:
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

Item

An item in the Amazon catalog.

NameDescriptionSchema
asin
required
The unique identifier of an item in the Amazon catalog.ItemAsin
attributes
optional
A JSON object containing structured item attribute data that is keyed by attribute name. Catalog item attributes conform to the related Amazon product type definitions that you can get from the Product Type Definitions API.ItemAttributes
classifications
optional
An array of classifications (browse nodes) that is associated with the item in the Amazon catalog, grouped by marketplaceId.ItemBrowseClassifications
dimensions
optional
An array of dimensions that are associated with the item in the Amazon catalog, grouped by marketplaceId.ItemDimensions
identifiers
optional
Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.ItemIdentifiers
images
optional
The images for an item in the Amazon catalog.ItemImages
productTypes
optional
Product types that are associated with the Amazon catalog item.ItemProductTypes
relationships
optional
Relationships grouped by marketplaceId for an Amazon catalog item (for example, variations).ItemRelationships
salesRanks
optional
Sales ranks of an Amazon catalog item.ItemSalesRanks
summaries
optional
Summaries of Amazon catalog items.ItemSummaries
vendorDetails
optional
The vendor details that are associated with an Amazon catalog item. Vendor details are only available to vendors.ItemVendorDetails

ItemAsin

The unique identifier of an item in the Amazon catalog.

Type : string

ItemAttributes

A JSON object containing structured item attribute data that is keyed by attribute name. Catalog item attributes conform to the related Amazon product type definitions that you can get from the Product Type Definitions API.

Type : object

ItemBrowseClassification

Classification (browse node) for an Amazon catalog item.

NameDescriptionSchema
displayName
required
Display name for the classification.string
classificationId
required
Identifier of the classification.string
parent
optional
Parent classification of the current classification.ItemBrowseClassification

ItemContributor

Individual contributor to the creation of an item, such as an author or actor.

NameDescriptionSchema
role
required
Role of an individual contributor in the creation of an item, such as author or actor.ItemContributorRole
value
required
Name of the contributor, such as Jane Austen.string

ItemContributorRole

Role of an individual contributor in the creation of an item, such as author or actor.

NameDescriptionSchema
displayName
optional
Display name of the role in the requested locale, such as Author or Actor.string
value
required
Role value for the Amazon catalog item, such as author or actor.string

ItemBrowseClassifications

An array of classifications (browse nodes) that is associated with the item in the Amazon catalog, grouped by marketplaceId.

Type : < ItemBrowseClassificationsByMarketplace > array

ItemBrowseClassificationsByMarketplace

Classifications (browse nodes) that are associated with the item in the Amazon catalog for the indicated marketplaceId.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.string
classifications
optional
Classifications (browse nodes) that are associated with the item in the Amazon catalog.< ItemBrowseClassification > array

Dimension

The value of an individual dimension for an Amazon catalog item or item package.

NameDescriptionSchema
unit
optional
Unit of measurement for the dimension value.string
value
optional
Numeric value of the dimension.number

Dimensions

Dimensions of an Amazon catalog item or item in its packaging.

NameDescriptionSchema
height
optional
Height of an item or item package.Dimension
length
optional
Length of an item or item package.Dimension
weight
optional
Weight of an item or item package.Dimension
width
optional
Width of an item or item package.Dimension

ItemDimensions

An array of dimensions that are associated with the item in the Amazon catalog, grouped by marketplaceId.

Type : < ItemDimensionsByMarketplace > array

ItemDimensionsByMarketplace

Dimensions that are associated with the item in the Amazon catalog for the indicated marketplaceId.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.string
item
optional
Dimensions of an Amazon catalog item.Dimensions
package
optional
Dimensions of a package that contains an Amazon catalog item.Dimensions

ItemIdentifiers

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

Type : < ItemIdentifiersByMarketplace > array

ItemIdentifiersByMarketplace

Identifiers that are associated with the item in the Amazon catalog, grouped by marketplaceId.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.identifier.string
identifiers
required
Identifiers associated with the item in the Amazon catalog for the indicated marketplaceId.< ItemIdentifier > array

ItemIdentifier

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

NameDescriptionSchema
identifierType
required
Type of identifier, such as UPC, EAN, or ISBN.string
identifier
required
Identifier of the item.string

ItemImages

The images for an item in the Amazon catalog.

Type : < ItemImagesByMarketplace > array

ItemImagesByMarketplace

Images for an item in the Amazon catalog, grouped by marketplaceId.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.string
images
required
Images for an item in the Amazon catalog, grouped by marketplaceId.< ItemImage > array

ItemImage

Image for an item in the Amazon catalog.

NameDescriptionSchema
variant
required
Variant of the image, such as MAIN or PT01.
Example : "MAIN"
enum (Variant)
link
required
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 that are associated with the Amazon catalog item.

Type : < ItemProductTypeByMarketplace > array

ItemProductTypeByMarketplace

Product type that is associated with the Amazon catalog item, grouped by marketplaceId.

NameDescriptionSchema
marketplaceId
optional
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.string
productType
optional
Name of the product type that is 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, grouped by marketplaceId.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.string
classificationRanks
optional
Sales ranks of an Amazon catalog item for a marketplaceId, grouped by classification.< ItemClassificationSalesRank > array
displayGroupRanks
optional
Sales ranks of an Amazon catalog item for a marketplaceId, grouped by website display group.< ItemDisplayGroupSalesRank > array

ItemClassificationSalesRank

Sales rank of an Amazon catalog item.

NameDescriptionSchema
classificationId
required
Identifier of the classification that is associated with the sales rank.string
title
required
Name of the sales rank.string
link
optional
Corresponding Amazon retail website URL for the sales category.string
rank
required
Sales rank.integer

ItemDisplayGroupSalesRank

Sales rank of an Amazon catalog item, grouped by website display group.

NameDescriptionSchema
websiteDisplayGroup
required
Name of the website display group that is associated with the sales rankstring
title
required
Name of the sales rank.string
link
optional
Corresponding Amazon retail website URL for the sales rank.string
rank
required
Sales rank.integer

ItemSummaries

Summaries of Amazon catalog items.

Type : < ItemSummaryByMarketplace > array

ItemSummaryByMarketplace

Information about an Amazon catalog item for the indicated marketplaceId.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.string
adultProduct
optional
When true, the Amazon catalog item is intended for an adult audience or is sexual in nature.boolean
autographed
optional
When true, the Amazon catalog item is autographed.boolean
brand
optional
Name of the brand that is associated with the Amazon catalog item.string
browseClassification
optional
Classification (browse node) that is associated with the Amazon catalog item.ItemBrowseClassification
color
optional
The color that is associated with the Amazon catalog item.string
contributors
optional
Individual contributors to the creation of the item, such as the authors or actors.< ItemContributor > array
itemClassification
optional
Classification type that is associated with the Amazon catalog item.enum (ItemClassification)
itemName
optional
The name that is associated with the Amazon catalog item.string
manufacturer
optional
The name of the manufacturer that is associated with the Amazon catalog item.string
memorabilia
optional
When true, the item is classified as memorabilia.boolean
modelNumber
optional
The model number that is associated with the Amazon catalog item.string
packageQuantity
optional
The quantity of the Amazon catalog item within one package.integer
partNumber
optional
The part number that is associated with the Amazon catalog item.string
releaseDate
optional
The earliest date on which the Amazon catalog item can be shipped to customers.string (date)
size
optional
The name of the size of the Amazon catalog item.string
style
optional
The name of the style that is associated with the Amazon catalog item.string
tradeInEligible
optional
When true, the Amazon catalog item is eligible for trade-in.boolean
websiteDisplayGroup
optional
The identifier of the website display group that is associated with the Amazon catalog item.string
websiteDisplayGroupName
optional
The display name of the website display group that is associated with the Amazon catalog item.string

ItemVariationTheme

The variation theme is a list of Amazon catalog item attributes that define the variation family.

NameDescriptionSchema
attributes
optional
Names of the Amazon catalog item attributes that are associated with the variation theme.< string > array
theme
optional
Variation theme that indicates the combination of Amazon catalog item attributes that define the variation family.
Example : "COLOR_NAME/STYLE_NAME"
string

ItemRelationships

Relationships grouped by marketplaceId for an Amazon catalog item (for example, variations).

Type : < ItemRelationshipsByMarketplace > array

ItemRelationshipsByMarketplace

Relationship details for the Amazon catalog item for the specified Amazon marketplaceId.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.string
relationships
required
Relationships for the item.< ItemRelationship > array

ItemRelationship

Relationship details for an Amazon catalog item.

NameDescriptionSchema
childAsins
optional
ASINs of the related items that are children of this item.< string > array
parentAsins
optional
ASINs of the related items that are parents of this item.< string > array
variationTheme
optional
For VARIATION relationships, the variation theme indicates the combination of Amazon catalog item attributes that define the variation family.ItemVariationTheme
type
required
Type of relationship.
Example : "VARIATION"
enum (Type)

ItemVendorDetailsCategory

The product category or subcategory that is associated with an Amazon catalog item.

NameDescriptionSchema
displayName
optional
The display name of the product category or subcategory.string
value
optional
The code that identifies the product category or subcategory.string

ItemVendorDetails

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

Type : < ItemVendorDetailsByMarketplace > array

ItemVendorDetailsByMarketplace

The vendor details that are associated with an Amazon catalog item for the specified marketplaceId.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier. To find the ID for your marketplace, refer to Marketplace IDs.string
brandCode
optional
The brand code that is associated with an Amazon catalog item.string
manufacturerCode
optional
The manufacturer code that is associated with an Amazon catalog item.string
manufacturerCodeParent
optional
The parent vendor code of the manufacturer code.string
productCategory
optional
The product category that is associated with an Amazon catalog item.ItemVendorDetailsCategory
productGroup
optional
The product group that is associated with an Amazon catalog item.string
productSubcategory
optional
The product subcategory that is associated with an Amazon catalog item.ItemVendorDetailsCategory
replenishmentCategory
optional
The replenishment category that is associated with an Amazon catalog item.enum (ReplenishmentCategory)

ItemSearchResults

Items in the Amazon catalog and search-related metadata.

NameDescriptionSchema
numberOfResults
required
For searches that are based on identifiers, numberOfResults is the total number of Amazon catalog items found. For searches that are based on keywords, numberOfResults is the estimated total number of Amazon catalog items that are matched by the search query. Only results up to the page count limit are returned per request regardless of the number found.

Note: The maximum number of items (ASINs) that can be returned and paged through is 1,000.
integer
pagination
required
The nextToken and previousToken values that are required to retrieve paginated results.Pagination
refinements
required
Search refinements for searches that are based on keywords.Refinements
items
required
A list of items from the Amazon catalog.< Item > array

Pagination

Pagination occurs when a request produces a response that exceeds the pageSize. This means that the response is divided into individual pages. To retrieve the next page or the previous page of results, you must pass the nextToken value or the previousToken value as the pageToken parameter in the next request. There is no nextToken in the pagination object on the last page.

NameDescriptionSchema
nextToken
optional
A token that you can use to retrieve the next page.string
previousToken
optional
A token that you can use to retrieve the previous page.string

Refinements

Optional fields that you can use to refine your search results.

NameDescriptionSchema
brands
required
A list of brands you can use to refine your search.< BrandRefinement > array
classifications
required
A list of classifications you can use to refine your search.< ClassificationRefinement > array

BrandRefinement

A brand that you can use to refine your search.

NameDescriptionSchema
numberOfResults
required
The estimated number of results that would be returned if you refine your search by the specified brandName.integer
brandName
required
The brand name that you can use to refine your search.string

ClassificationRefinement

A classification that you can use to refine your search.

NameDescriptionSchema
numberOfResults
required
The estimated number of results that would be returned if you refine your search by the specified classificationId.integer
displayName
required
Display name for the classification.string
classificationId
required
The identifier of the classification that you can use to refine your search.string

Variant

Variant of the image, such as MAIN or PT01.

Type : enum

ValueDescription
MAINMain image for the item
PT01Other image #1 for the item
PT02Other image #2 for the item
PT03Other image #3 for the item
PT04Other image #4 for the item
PT05Other image #5 for the item
PT06Other image #6 for the item
PT07Other image #7 for the item
PT08Other image #8 for the item
SWCHSwatch image for the item

IdentifiersType

The type of product identifiers that you can use to search the Amazon catalog. Note: identifiersType is required when identifiers is in the request.

Type : enum

ValueDescription
ASINAmazon Standard Identification Number
EANEuropean Article Number
GTINGlobal Trade Item Number
ISBNInternational Standard Book Number
JANJapanese Article Number
MINSANMinsan Code
SKUStock Keeping Unit, a seller-specified identifier for an Amazon listing. Note: Must be accompanied by sellerId.
UPCUniversal Product Code

ItemClassification

Classification type that is associated with the Amazon catalog item.

Type : enum

ValueDescription
BASE_PRODUCTA product that can be directly purchased. Can be a standalone ASIN or a variation child item in the Amazon catalog.
OTHERAn item in the Amazon catalog that is not BASE_PRODUCT, PRODUCT_BUNDLE, or VARIATION_PARENT.
PRODUCT_BUNDLEA parent catalog item that represents a bundle of items.
VARIATION_PARENTA parent catalog item that groups child items into a variation family.

Type

Type of relationship.

Type : enum

ValueDescription
VARIATIONThe Amazon catalog item in the request is a variation parent or variation child of the related items that are identified by ASIN.
PACKAGE_HIERARCHYThe Amazon catalog item in the request is a package container or is contained by the related items that are identified by ASIN.

ReplenishmentCategory

The replenishment category that is associated with an Amazon catalog item.

Type : enum

ValueDescription
ALLOCATEDThe vendor allocates the inventory to Amazon and Amazon manually purchases it.
BASIC_REPLENISHMENTInventory is manually purchased.
IN_SEASONSeasonal item that is manually purchased.
LIMITED_REPLENISHMENTAmazon generates orders for this item automatically based on unfilled demand.
MANUFACTURER_OUT_OF_STOCKThe vendor is out of stock for an extended period of time and cannot backorder.
NEW_PRODUCTAmazon does not yet stock this item.
NON_REPLENISHABLEIndicates assortment parent used for detail page display, not actual items.
NON_STOCKUPABLEDrop ship inventory that Amazon does not stock in its fulfillment centers.
OBSOLETEThe item is obsolete and should not be ordered.
PLANNED_REPLENISHMENTActive items that should be automatically ordered.

IncludedData

Type : enum

For use with the operation(s): getCatalogItem

ValueDescription
attributesA JSON object containing structured item attribute data that is keyed by attribute name. Catalog item attributes conform to the related Amazon product type definitions that you can get from the Product Type Definitions API.
classificationsClassifications (browse nodes) for an item in the Amazon catalog.
dimensionsDimensions of an item in the Amazon catalog.
identifiersIdentifiers that are associated with the item in the Amazon catalog, such as UPC and EA.
imagesImages for an item in the Amazon catalog.
productTypesProduct types associated with the Amazon catalog item.
relationshipsRelationship details of an Amazon catalog item (for example, variations).
salesRanksSales ranks of an Amazon catalog item.
summariesSummary of an Amazon catalog item. For more information, refer to the attributes of an Amazon catalog item.
vendorDetailsVendor details associated with an Amazon catalog item. Vendor details are only available to vendors.

For use with the operation(s): searchCatalogItems

ValueDescription
attributesA JSON object containing structured item attribute data that is keyed by attribute name. Catalog item attributes conform to the related Amazon product type definitions that you can get from the Product Type Definitions API.
classificationsClassifications (browse nodes) for an item in the Amazon catalog.
dimensionsDimensions of an item in the Amazon catalog.
identifiersIdentifiers that are associated with the item in the Amazon catalog, such as UPC and EAN.
imagesImages for an item in the Amazon catalog.
productTypesProduct types associated with the Amazon catalog item.
relationshipsRelationship details of an Amazon catalog item (for example, variations).
salesRanksSales ranks of an Amazon catalog item.
summariesSummary of an Amazon catalog item. For more information, refer to the attributes of an Amazon catalog item.
vendorDetailsVendor details associated with an Amazon catalog item. Vendor details are only available to vendors.

Did this page help you?