Catalog Items API v2022-04-01 reference

Swagger model for the Catalog Items API v2022-04-01.

Overview

The Selling Partner API for Catalog Items provides programmatic access to 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 and return a list of Amazon catalog items and associated information either by identifier or by keywords.

Usage Plans:

Rate (requests per second)Burst
55

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may observe higher rate and burst values than those shown here. For more information, refer to the Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchemaDefault
Queryidentifiers
optional
A comma-delimited list of product identifiers to search the Amazon catalog for. Note: Cannot be used with keywords.
Max count : 20
< string > array(csv)-
QueryidentifiersType
optional
Type of product identifiers to search the Amazon catalog for. Note: Required when identifiers are provided.enum (IdentifiersType)-
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers for the request.
Max count : 1
< string > array(csv)-
QueryincludedData
optional
A comma-delimited list of data sets to include in the response. Default: summaries.< enum (IncludedData) > array(csv)"[\"summaries\"]"
Querylocale
optional
Locale for retrieving 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 words to search the Amazon catalog for. Note: Cannot be used with identifiers.
Max count : 20
< string > array(csv)-
QuerybrandNames
optional
A comma-delimited list of brand names to limit the search for keywords-based queries. Note: Cannot be used with identifiers.< string > array(csv)-
QueryclassificationIds
optional
A comma-delimited list of classification identifiers to limit the search for keywords-based queries. Note: Cannot be used with identifiers.< string > array(csv)-
QuerypageSize
optional
Number of results to be returned per page.
Maximum : 20
integer10
QuerypageToken
optional
A token to fetch a certain page when there are multiple pages worth of results.string-
QuerykeywordsLocale
optional
The language of the keywords provided for keywords-based queries. 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 returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may observe higher rate and burst values than those shown here. For more information, refer to the Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchemaDefault
Pathasin
required
The Amazon Standard Identification Number (ASIN) of the item.string-
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers. Data sets in the response contain data only for the specified marketplaces.< string > array(csv)-
QueryincludedData
optional
A comma-delimited list of data sets to include in the response. Default: summaries.< enum (IncludedData) > array(csv)"[\"summaries\"]"
Querylocale
optional
Locale for retrieving 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
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 conform to the related product type definitions available in the Selling Partner API for Product Type Definitions.ItemAttributes
dimensions
optional
Array of dimensions associated with the item in the Amazon catalog by Amazon marketplace.ItemDimensions
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.ItemImages
productTypes
optional
Product types associated with the Amazon catalog item.ItemProductTypes
relationships
optional
Relationships by marketplace for an Amazon catalog item (for example, variations).ItemRelationships
salesRanks
optional
Sales ranks of an Amazon catalog item.ItemSalesRanks
summaries
optional
Summary details of an Amazon catalog item.ItemSummaries
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 conform to the related product type definitions available in the Selling Partner API for Product Type Definitions.

Type : object

ItemBrowseClassification

Classification (browse node) associated with an Amazon catalog item.

NameDescriptionSchema
displayName
required
Display name for the classification.string
classificationId
required
Identifier of the classification (browse node identifier).string

Dimension

Individual dimension value of an Amazon catalog item or item package.

NameDescriptionSchema
unit
optional
Measurement unit of the dimension value.string
value
optional
Numeric dimension value.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

Array of dimensions associated with the item in the Amazon catalog by Amazon marketplace.

Type : < ItemDimensionsByMarketplace > array

ItemDimensionsByMarketplace

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

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier.string
item
optional
Dimensions of an Amazon catalog item.Dimensions
package
optional
Dimensions of an Amazon catalog item in its packaging.Dimensions

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.

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

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

Type : < ItemImagesByMarketplace > array

ItemImagesByMarketplace

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

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

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

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

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier.string
classificationRanks
optional
Sales ranks of an Amazon catalog item for an Amazon marketplace by classification.< ItemClassificationSalesRank > array
displayGroupRanks
optional
Sales ranks of an Amazon catalog item for an Amazon marketplace by website display group.< ItemDisplayGroupSalesRank > array

ItemClassificationSalesRank

Sales rank of an Amazon catalog item by classification.

NameDescriptionSchema
classificationId
required
Identifier of the classification associated with the sales rank.string
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

ItemDisplayGroupSalesRank

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

NameDescriptionSchema
websiteDisplayGroup
required
Name of the website display group associated with the sales rankstring
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.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier.string
brand
optional
Name of the brand associated with an Amazon catalog item.string
browseClassification
optional
Classification (browse node) associated with an Amazon catalog item.ItemBrowseClassification
color
optional
Name of the color associated with an Amazon catalog item.string
itemClassification
optional
Classification type associated with the Amazon catalog item.enum (ItemClassification)
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
packageQuantity
optional
Quantity of an Amazon catalog item in one package.integer
partNumber
optional
Part number associated with an Amazon catalog item.string
size
optional
Name of the size associated with an Amazon catalog item.string
style
optional
Name of the style associated with an Amazon catalog item.string
websiteDisplayGroup
optional
Name of the website display group associated with an Amazon catalog item.string

ItemVariationTheme

Variation theme indicating the combination of Amazon item catalog attributes that define the variation family.

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

ItemRelationships

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

Type : < ItemRelationshipsByMarketplace > array

ItemRelationshipsByMarketplace

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

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier.string
relationships
required
Relationships for the item.< ItemRelationship > array

ItemRelationship

Relationship details for an Amazon catalog item.

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

ItemVendorDetailsCategory

Product category or subcategory associated with an Amazon catalog item.

NameDescriptionSchema
displayName
optional
Display name of the product category or subcategorystring
value
optional
Value (code) of the product category or subcategory.string

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.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier.string
brandCode
optional
Brand code 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
productCategory
optional
Product category associated with an Amazon catalog item.ItemVendorDetailsCategory
productGroup
optional
Product group associated with an Amazon catalog item.string
productSubcategory
optional
Product subcategory associated with an Amazon catalog item.ItemVendorDetailsCategory
replenishmentCategory
optional
Replenishment category associated with an Amazon catalog item.enum (ReplenishmentCategory)

ItemSearchResults

Items in the Amazon catalog and search related metadata.

NameDescriptionSchema
numberOfResults
required
For identifiers-based searches, the total number of Amazon catalog items found. For keywords-based searches, the estimated total number of Amazon catalog items 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 for keywords-based searches.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.

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

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

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

NameDescriptionSchema
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

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

Type of product identifiers to search the Amazon catalog for. Note: Required when identifiers are provided.

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 associated with the Amazon catalog item.

Type : enum

ValueDescription
BASE_PRODUCTRepresents a standard standalone or a variation child item in the Amazon catalog.
OTHERRepresents an item in the Amazon catalog that is not BASE_PRODUCT, PRODUCT_BUNDLE, or VARIATION_PARENT.
PRODUCT_BUNDLERepresents a parent Amazon catalog item representing a bundle of items.
VARIATION_PARENTRepresents a parent Amazon catalog item grouping 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 item(s) indicated by ASIN.
PACKAGE_HIERARCHYThe Amazon catalog item in the request is a package container or is contained by the related item(s) indicated by ASIN.

ReplenishmentCategory

Replenishment category associated with an Amazon catalog item.

Type : enum

ValueDescription
ALLOCATEDIndicates non-automated purchasing of inventory that has been allocated to Amazon by the vendor.
BASIC_REPLENISHMENTIndicates non-automated purchasing of inventory.
IN_SEASONIndicates non-automated purchasing of inventory for seasonal items.
LIMITED_REPLENISHMENTHolding queue replenishment status before an item is NEW_PRODUCT.
MANUFACTURER_OUT_OF_STOCKIndicates vendor is out of stock for a longer period of time and cannot backorder.
NEW_PRODUCTIndicates a new item that Amazon does not yet stock in inventory.
NON_REPLENISHABLEIndicates assortment parent used for detail page display, not actual items.
NON_STOCKUPABLEIndicates drop ship inventory that Amazon does not stock in its fulfillment centers.
OBSOLETEIndicates item is obsolete and should not be ordered.
PLANNED_REPLENISHMENTIndicates active 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 keyed by attribute name. Catalog item attributes conform to the related Amazon product type definitions available in the Selling Partner API for Product Type Definitions.
dimensionsDimensions for an item in the Amazon catalog.
identifiersIdentifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.
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 details of an Amazon catalog item. Refer to the "attributes" of an Amazon catalog item for more details.
vendorDetailsVendor details associated with an Amazon catalog item. Vendor details are available to vendors only.

For use with the operation(s): searchCatalogItems

ValueDescription
attributesA JSON object containing structured item attribute data keyed by attribute name. Catalog item attributes conform to the related Amazon product type definitions available in the Selling Partner API for Product Type Definitions.
dimensionsDimensions for an item in the Amazon catalog.
identifiersIdentifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.
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 details of an Amazon catalog item. Refer to the attributes of an Amazon catalog item for more details.
vendorDetailsVendor details associated with an Amazon catalog item. Vendor details are available to vendors only.