# Overview
The Selling Partner API for Catalog Items helps you programmatically retrieve item details for items in the catalog.
# Version information
Version : v0
# Operations
listCatalogItems
getCatalogItem
listCatalogCategories
# Paths
# listCatalogItems
GET /catalog/v0/items
# 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 Plans:
| Plan type | Rate (requests per second) | Burst |
|---|---|---|
| Default | 6 | 40 |
| 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 documentation.
# Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Query | MarketplaceId required | A marketplace identifier. Specifies the marketplace for which items are returned. | string |
| Query | Query optional | Keyword(s) to use to search for items in the catalog. Example: 'harry potter books'. | string |
| Query | QueryContextId 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 |
| Query | SellerSKU 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 |
| Query | UPC optional | A 12-digit bar code used for retail packaging. | string |
| Query | EAN optional | A European article number that uniquely identifies the catalog item, manufacturer, and its attributes. | string |
| Query | ISBN optional | The unique commercial book identifier used to identify books internationally. | string |
| Query | JAN optional | A Japanese article number that uniquely identifies the product, manufacturer, and its attributes. | 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 ID. | ListCatalogItemsResponse |
| 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 ID. | ListCatalogItemsResponse |
| 401 | The 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 |
| 403 | Indicates 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 |
| 404 | The 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 |
| 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 ID. | ListCatalogItemsResponse |
| 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 ID. | ListCatalogItemsResponse |
| 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 ID. | ListCatalogItemsResponse |
# getCatalogItem
GET /catalog/v0/items/{asin}
# Description
Returns a specified item and its attributes.
Usage Plans:
| Plan type | Rate (requests per second) | Burst |
|---|---|---|
| Default | 2 | 20 |
| 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 documentation.
# Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Query | MarketplaceId required | A marketplace identifier. Specifies the marketplace for the item. | string |
| Path | asin required | The Amazon Standard Identification Number (ASIN) of the item. | 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 ID. | GetCatalogItemResponse |
| 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 ID. | GetCatalogItemResponse |
| 401 | The 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 |
| 403 | Indicates 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 |
| 404 | The 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 |
| 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 ID. | GetCatalogItemResponse |
| 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 ID. | GetCatalogItemResponse |
| 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 ID. | GetCatalogItemResponse |
# listCatalogCategories
GET /catalog/v0/categories
# Description
Returns the parent categories to which an item belongs, based on the specified ASIN or SellerSKU.
Usage Plans:
| Plan type | Rate (requests per second) | Burst |
|---|---|---|
| Default | 1 | 40 |
| 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 documentation.
# Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Query | MarketplaceId required | A marketplace identifier. Specifies the marketplace for the item. | string |
| Query | ASIN optional | The Amazon Standard Identification Number (ASIN) of the item. | string |
| Query | SellerSKU 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 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 ID. | ListCatalogCategoriesResponse |
| 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 ID. | ListCatalogCategoriesResponse |
| 401 | The 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 |
| 403 | Indicates 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 |
| 404 | The 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 |
| 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 ID. | ListCatalogCategoriesResponse |
| 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 ID. | ListCatalogCategoriesResponse |
| 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 ID. | ListCatalogCategoriesResponse |
# Definitions
# ListCatalogItemsResponse
| Name | Description | Schema |
|---|---|---|
| payload optional | The payload for the listCatalogItems operation. | ListMatchingItemsResponse |
| errors optional | One or more unexpected errors occurred during the listCatalogItems operation. | ErrorList |
# ListMatchingItemsResponse
| Name | Description | Schema |
|---|---|---|
| Items optional | A list of items. | ItemList |
# ItemList
A list of items.
Type : < Item > array
# GetCatalogItemResponse
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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
| Name | Description | Schema |
|---|---|---|
| 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
| Name | Description | Schema |
|---|---|---|
| MarketplaceId required | A marketplace identifier. | string |
| ASIN required | The Amazon Standard Identification Number (ASIN) of the item. | string |
# SellerSKUIdentifier
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| value optional | The decimal value. | number |
| Units optional | The unit of the decimal value. | string |
# CreatorType
The creator type attribute of an item.
| Name | Description | Schema |
|---|---|---|
| value optional | The value of the attribute. | string |
| Role optional | The role of the value. | string |
# DimensionType
The dimension type attribute of an item.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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
| Name | Description | Schema |
|---|---|---|
| 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
| Name | Description | Schema |
|---|---|---|
| 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
| Name | Description | Schema |
|---|---|---|
| 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.
| 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 in a human-readable form. | string |
| details optional | Additional information that can help the caller understand or fix the issue. | string |