Catalog Items API v0 reference

Swagger model for the Catalog Items API v0.

Overview

The Selling Partner API for Catalog Items helps you programmatically retrieve item details for items in the catalog.

Version information

Version : v0

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

listCatalogItems
getCatalogItem
listCatalogCategories

Paths

GET /catalog/v0/items

Operation: listCatalogItems

Description

Returns a list of items and their attributes, based on a search query or item identifiers that you specify. When based on a search query, provide the Query parameter and optionally, the QueryContextId parameter. When based on item identifiers, provide a single appropriate parameter based on the identifier type, and specify the associated item value.

MarketplaceId is always required. At least one of Query, SellerSKU, UPC, EAN, ISBN, JAN is also required.

This operation returns a maximum of ten products and does not return non-buyable products.

Usage Plan:

Rate (requests per second)Burst
deprecateddeprecated

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 see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
QueryMarketplaceId
required
A marketplace identifier. Specifies the marketplace for which items are returned.string
QueryQuery
optional
Keyword(s) to use to search for items in the catalog. Example: 'harry potter books'.string
QueryQueryContextId
optional
An identifier for the context within which the given search will be performed. A marketplace might provide mechanisms for constraining a search to a subset of potential items. For example, the retail marketplace allows queries to be constrained to a specific category. The QueryContextId parameter specifies such a subset. If it is omitted, the search will be performed using the default context for the marketplace, which will typically contain the largest set of items.string
QuerySellerSKU
optional
Used to identify an item in the given marketplace. SellerSKU is qualified by the seller's SellerId, which is included with every operation that you submit.string
QueryUPC
optional
A 12-digit bar code used for retail packaging.string
QueryEAN
optional
A European article number that uniquely identifies the catalog item, manufacturer, and its attributes.string
QueryISBN
optional
The unique commercial book identifier used to identify books internationally.string
QueryJAN
optional
A Japanese article number that uniquely identifies the product, manufacturer, and its attributes.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 ID.
ListCatalogItemsResponse
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 ID.
ListCatalogItemsResponse
401The request's Authorization header is not formatted correctly or does not contain a valid token.
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 ID.
ListCatalogItemsResponse
403Indicates 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 ID.
ListCatalogItemsResponse
404The specified resource 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 ID.
ListCatalogItemsResponse
429The 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 ID.
ListCatalogItemsResponse
500An 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 ID.
ListCatalogItemsResponse
503Temporary 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 ID.
ListCatalogItemsResponse

GET /catalog/v0/items/{asin}

Operation: getCatalogItem

Description

Returns a specified item and its attributes.

Usage Plan:

Rate (requests per second)Burst
deprecateddeprecated

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 see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
QueryMarketplaceId
required
A marketplace identifier. Specifies the marketplace for the item.string
Pathasin
required
The Amazon Standard Identification Number (ASIN) of the item.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 ID.
GetCatalogItemResponse
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 ID.
GetCatalogItemResponse
401The request's Authorization header is not formatted correctly or does not contain a valid token.
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 ID.
GetCatalogItemResponse
403Indicates 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 ID.
GetCatalogItemResponse
404The specified resource 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 ID.
GetCatalogItemResponse
429The 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 ID.
GetCatalogItemResponse
500An 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 ID.
GetCatalogItemResponse
503Temporary 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 ID.
GetCatalogItemResponse

GET /catalog/v0/categories

Operation: listCatalogCategories

Description

Returns the parent categories to which an item belongs, based on the specified ASIN or SellerSKU.

Usage Plan:

Rate (requests per second)Burst
12

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 see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
QueryMarketplaceId
required
A marketplace identifier. Specifies the marketplace for the item.string
QueryASIN
optional
The Amazon Standard Identification Number (ASIN) of the item.string
QuerySellerSKU
optional
Used to identify items in the given marketplace. SellerSKU is qualified by the seller's SellerId, which is included with every operation that you submit.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 ID.
ListCatalogCategoriesResponse
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 ID.
ListCatalogCategoriesResponse
401The request's Authorization header is not formatted correctly or does not contain a valid token.
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 ID.
ListCatalogCategoriesResponse
403Indicates 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 ID.
ListCatalogCategoriesResponse
404The specified resource 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 ID.
ListCatalogCategoriesResponse
429The 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 ID.
ListCatalogCategoriesResponse
500An 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 ID.
ListCatalogCategoriesResponse
503Temporary 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 ID.
ListCatalogCategoriesResponse

Definitions

ListCatalogItemsResponse

NameDescriptionSchema
payload
optional
The payload for the listCatalogItems operation.ListMatchingItemsResponse
errors
optional
One or more unexpected errors occurred during the listCatalogItems operation.ErrorList

ListMatchingItemsResponse

NameDescriptionSchema
Items
optional
A list of items.ItemList

ItemList

A list of items.

Type : < Item > array

GetCatalogItemResponse

NameDescriptionSchema
payload
optional
The payload for the getCatalogItem operation.Item
errors
optional
One or more unexpected errors occurred during the getCatalogItem operation.ErrorList

Item

An item in the Amazon catalog.

NameDescriptionSchema
Identifiers
required
The identifiers that uniquely identify the item.IdentifierType
AttributeSets
optional
A list of attributes of the item.AttributeSetList
Relationships
optional
A list of variation relationship information for the item.RelationshipList
SalesRankings
optional
A list of sales rank information for the item by category.SalesRankList

IdentifierType

NameDescriptionSchema
MarketplaceASIN
optional
Indicates the item is identified by MarketPlaceId and ASIN.ASINIdentifier
SKUIdentifier
optional
Indicates the item is identified by MarketPlaceId, SellerId, and SellerSKU.SellerSKUIdentifier

ASINIdentifier

NameDescriptionSchema
MarketplaceId
required
A marketplace identifier.string
ASIN
required
The Amazon Standard Identification Number (ASIN) of the item.string

SellerSKUIdentifier

NameDescriptionSchema
MarketplaceId
required
A marketplace identifier.string
SellerId
required
The seller identifier submitted for the operation.string
SellerSKU
required
The seller stock keeping unit (SKU) of the item.string

AttributeSetList

A list of attributes for the item.

Type : < AttributeSetListType > array

AttributeSetListType

The attributes of the item.

NameDescriptionSchema
Actor
optional
The actor attributes of the item.< string > array
Artist
optional
The artist attributes of the item.< string > array
AspectRatio
optional
The aspect ratio attribute of the item.string
AudienceRating
optional
The audience rating attribute of the item.string
Author
optional
The author attributes of the item.< string > array
BackFinding
optional
The back finding attribute of the item.string
BandMaterialType
optional
The band material type attribute of the item.string
Binding
optional
The binding attribute of the item.string
BlurayRegion
optional
The Bluray region attribute of the item.string
Brand
optional
The brand attribute of the item.string
CeroAgeRating
optional
The CERO age rating attribute of the item.string
ChainType
optional
The chain type attribute of the item.string
ClaspType
optional
The clasp type attribute of the item.string
Color
optional
The color attribute of the item.string
CpuManufacturer
optional
The CPU manufacturer attribute of the item.string
CpuSpeed
optional
The CPU speed attribute of the item.DecimalWithUnits
CpuType
optional
The CPU type attribute of the item.string
Creator
optional
The creator attributes of the item.< CreatorType > array
Department
optional
The department attribute of the item.string
Director
optional
The director attributes of the item.< string > array
DisplaySize
optional
The display size attribute of the item.DecimalWithUnits
Edition
optional
The edition attribute of the item.string
EpisodeSequence
optional
The episode sequence attribute of the item.string
EsrbAgeRating
optional
The ESRB age rating attribute of the item.string
Feature
optional
The feature attributes of the item< string > array
Flavor
optional
The flavor attribute of the item.string
Format
optional
The format attributes of the item.< string > array
GemType
optional
The gem type attributes of the item.< string > array
Genre
optional
The genre attribute of the item.string
GolfClubFlex
optional
The golf club flex attribute of the item.string
GolfClubLoft
optional
The golf club loft attribute of the item.DecimalWithUnits
HandOrientation
optional
The hand orientation attribute of the item.string
HardDiskInterface
optional
The hard disk interface attribute of the item.string
HardDiskSize
optional
The hard disk size attribute of the item.DecimalWithUnits
HardwarePlatform
optional
The hardware platform attribute of the item.string
HazardousMaterialType
optional
The hazardous material type attribute of the item.string
ItemDimensions
optional
The item dimensions attribute of the item.DimensionType
IsAdultProduct
optional
The adult product attribute of the item.boolean
IsAutographed
optional
The autographed attribute of the item.boolean
IsEligibleForTradeIn
optional
The is eligible for trade in attribute of the item.boolean
IsMemorabilia
optional
The is memorabilia attribute of the item.boolean
IssuesPerYear
optional
The issues per year attribute of the item.string
ItemPartNumber
optional
The item part number attribute of the item.string
Label
optional
The label attribute of the item.string
Languages
optional
The languages attribute of the item.< LanguageType > array
LegalDisclaimer
optional
The legal disclaimer attribute of the item.string
ListPrice
optional
The list price attribute of the item.Price
Manufacturer
optional
The manufacturer attribute of the item.string
ManufacturerMaximumAge
optional
The manufacturer maximum age attribute of the item.DecimalWithUnits
ManufacturerMinimumAge
optional
The manufacturer minimum age attribute of the item.DecimalWithUnits
ManufacturerPartsWarrantyDescription
optional
The manufacturer parts warranty description attribute of the item.string
MaterialType
optional
The material type attributes of the item.< string > array
MaximumResolution
optional
The maximum resolution attribute of the item.DecimalWithUnits
MediaType
optional
The media type attributes of the item.< string > array
MetalStamp
optional
The metal stamp attribute of the item.string
MetalType
optional
The metal type attribute of the item.string
Model
optional
The model attribute of the item.string
NumberOfDiscs
optional
The number of discs attribute of the item.integer
NumberOfIssues
optional
The number of issues attribute of the item.integer
NumberOfItems
optional
The number of items attribute of the item.integer
NumberOfPages
optional
The number of pages attribute of the item.integer
NumberOfTracks
optional
The number of tracks attribute of the item.integer
OperatingSystem
optional
The operating system attributes of the item.< string > array
OpticalZoom
optional
The optical zoom attribute of the item.DecimalWithUnits
PackageDimensions
optional
The package dimensions attribute of the item.DimensionType
PackageQuantity
optional
The package quantity attribute of the item.integer
PartNumber
optional
The part number attribute of the item.string
PegiRating
optional
The PEGI rating attribute of the item.string
Platform
optional
The platform attributes of the item.< string > array
ProcessorCount
optional
The processor count attribute of the item.integer
ProductGroup
optional
The product group attribute of the item.string
ProductTypeName
optional
The product type name attribute of the item.string
ProductTypeSubcategory
optional
The product type subcategory attribute of the item.string
PublicationDate
optional
The publication date attribute of the item.string
Publisher
optional
The publisher attribute of the item.string
RegionCode
optional
The region code attribute of the item.string
ReleaseDate
optional
The release date attribute of the item.string
RingSize
optional
The ring size attribute of the item.string
RunningTime
optional
The running time attribute of the item.DecimalWithUnits
ShaftMaterial
optional
The shaft material attribute of the item.string
Scent
optional
The scent attribute of the item.string
SeasonSequence
optional
The season sequence attribute of the item.string
SeikodoProductCode
optional
The Seikodo product code attribute of the item.string
Size
optional
The size attribute of the item.string
SizePerPearl
optional
The size per pearl attribute of the item.string
SmallImage
optional
The small image attribute of the item.Image
Studio
optional
The studio attribute of the item.string
SubscriptionLength
optional
The subscription length attribute of the item.DecimalWithUnits
SystemMemorySize
optional
The system memory size attribute of the item.DecimalWithUnits
SystemMemoryType
optional
The system memory type attribute of the item.string
TheatricalReleaseDate
optional
The theatrical release date attribute of the item.string
Title
optional
The title attribute of the item.string
TotalDiamondWeight
optional
The total diamond weight attribute of the item.DecimalWithUnits
TotalGemWeight
optional
The total gem weight attribute of the item.DecimalWithUnits
Warranty
optional
The warranty attribute of the item.string
WeeeTaxValue
optional
The WEEE tax value attribute of the item.Price

DecimalWithUnits

The decimal value and unit.

NameDescriptionSchema
value
optional
The decimal value.number
Units
optional
The unit of the decimal value.string

CreatorType

The creator type attribute of an item.

NameDescriptionSchema
value
optional
The value of the attribute.string
Role
optional
The role of the value.string

DimensionType

The dimension type attribute of an item.

NameDescriptionSchema
Height
optional
The height attribute of the dimension.DecimalWithUnits
Length
optional
The length attribute of the dimension.DecimalWithUnits
Width
optional
The width attribute of the dimension.DecimalWithUnits
Weight
optional
The weight attribute of the dimension.DecimalWithUnits

LanguageType

The language type attribute of an item.

NameDescriptionSchema
Name
optional
The name attribute of the item.string
Type
optional
The type attribute of the item.string
AudioFormat
optional
The audio format attribute of the item.string

Image

The image attribute of the item.

NameDescriptionSchema
URL
optional
The image URL attribute of the item.string
Height
optional
The image height attribute of the item.DecimalWithUnits
Width
optional
The image width attribute of the item.DecimalWithUnits

Price

The price attribute of the item.

NameDescriptionSchema
Amount
optional
The amount.number
CurrencyCode
optional
The currency code of the amount.string

RelationshipList

A list of variation relationship information, if applicable for the item.

Type : < RelationshipType > array

RelationshipType

Specific variations of the item.

NameDescriptionSchema
Identifiers
optional
The identifiers that uniquely identify the item that is related.IdentifierType
Color
optional
The color variation of the item.string
Edition
optional
The edition variation of the item.string
Flavor
optional
The flavor variation of the item.string
GemType
optional
The gem type variations of the item.< string > array
GolfClubFlex
optional
The golf club flex variation of an item.string
HandOrientation
optional
The hand orientation variation of an item.string
HardwarePlatform
optional
The hardware platform variation of an item.string
MaterialType
optional
The material type variations of an item.< string > array
MetalType
optional
The metal type variation of an item.string
Model
optional
The model variation of an item.string
OperatingSystem
optional
The operating system variations of an item.< string > array
ProductTypeSubcategory
optional
The product type subcategory variation of an item.string
RingSize
optional
The ring size variation of an item.string
ShaftMaterial
optional
The shaft material variation of an item.string
Scent
optional
The scent variation of an item.string
Size
optional
The size variation of an item.string
SizePerPearl
optional
The size per pearl variation of an item.string
GolfClubLoft
optional
The golf club loft variation of an item.DecimalWithUnits
TotalDiamondWeight
optional
The total diamond weight variation of an item.DecimalWithUnits
TotalGemWeight
optional
The total gem weight variation of an item.DecimalWithUnits
PackageQuantity
optional
The package quantity variation of an item.integer
ItemDimensions
optional
The item dimensions relationship of an item.DimensionType

SalesRankList

A list of sales rank information for the item by category.

Type : < SalesRankType > array

SalesRankType

NameDescriptionSchema
ProductCategoryId
required
Identifies the item category from which the sales rank is taken.string
Rank
required
The sales rank of the item within the item category.integer (int32)

ListCatalogCategoriesResponse

NameDescriptionSchema
payload
optional
The payload for the listCatalogCategories operation.ListOfCategories
errors
optional
One or more unexpected errors occurred during the listCatalogCategories operation.ErrorList

ListOfCategories

Type : < Categories > array

Categories

NameDescriptionSchema
ProductCategoryId
optional
The identifier for the product category (or browse node).string
ProductCategoryName
optional
The name of the product category (or browse node).string
parent
optional
The parent product category.object

ErrorList

A list of error responses returned when a request is unsuccessful.

Type : < Error > array

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 in a human-readable form.string
details
optional
Additional information that can help the caller understand or fix the issue.string

Did this page help you?