Catalog Items API v2020-12-01 Reference
Use Catalog Items to gain programmatic access to information contained in the Amazon catalog.
Overview
The Selling Partner API for Catalog Items provides programmatic access to information about items in the Amazon catalog.
For more information, see the Catalog Items API Use Case Guide.
Version information
Version : 2020-12-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/2020-12-01/items
Operation: searchCatalogItems
Description
Search for and return a list of Amazon catalog items and associated information.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 2 | 2 |
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
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
| Query | keywords required | A comma-delimited list of words or item identifiers to search the Amazon catalog for. | < string > array(csv) | - |
| Query | marketplaceIds required | A comma-delimited list of Amazon marketplace identifiers for the request. Max count : 1 | < string > array(csv) | - |
| Query | includedData optional | A comma-delimited list of data sets to include in the response. Default: summaries. | < enum (IncludedData) > array(csv) | - |
| Query | brandNames optional | A comma-delimited list of brand names to limit the search to. | < string > array(csv) | - |
| Query | classificationIds optional | A comma-delimited list of classification identifiers to limit the search to. | < string > array(csv) | - |
| Query | pageSize optional | Number of results to be returned per page. Maximum : 20 | integer | 10 |
| Query | pageToken optional | A token to fetch a certain page when there are multiple pages worth of results. | string | - |
| Query | keywordsLocale optional | The language the keywords are provided in. Defaults to the primary locale of the marketplace. | string | - |
| Query | locale optional | Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace. | string | - |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | ItemSearchResults |
For error status codes, descriptions and schemas, see Error responses and schemas.
Consumes
application/json
Produces
application/json
GET /catalog/2020-12-01/items/{asin}
Operation: getCatalogItem
Description
Retrieves details for an item in the Amazon catalog.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 2 | 2 |
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
| Type | Name | Description | Schema |
|---|---|---|---|
| Path | asin required | The Amazon Standard Identification Number (ASIN) of the item. | string |
| Query | marketplaceIds required | A comma-delimited list of Amazon marketplace identifiers. Data sets in the response contain data only for the specified marketplaces. | < string > array(csv) |
| Query | includedData optional | A comma-delimited list of data sets to include in the response. Default: summaries. | < enum (IncludedData) > array(csv) |
| Query | locale optional | Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | Item |
For error status codes, descriptions and schemas, see Error responses and schemas.
Consumes
application/json
Produces
application/json
Error Responses and Schemas
This table contains HTTP status codes and associated information for error responses.
| HTTP Code | Description | Schema |
|---|---|---|
| 400 | Request has missing or invalid parameters and cannot be parsed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 404 | The resource specified does not exist. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 413 | The request size exceeded the maximum accepted size. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 415 | The request payload is in an unsupported format. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 429 | The frequency of requests was greater than allowed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 503 | Temporary overloading or maintenance of the server. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
Definitions
Error
Error response returned when the request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| code required | An error code that identifies the type of error that occurred. | string |
| message required | A message that describes the error condition. | string |
| details optional | Additional details that can help the caller understand or fix the issue. | string |
ErrorList
A list of error responses returned when a request is unsuccessful.
| Name | Schema |
|---|---|
| errors required | < Error > array |
Item
An item in the Amazon catalog.
| Name | Description | Schema |
|---|---|---|
| asin required | Amazon Standard Identification Number (ASIN) is the unique identifier for an item in the Amazon catalog. | ItemAsin |
| attributes optional | A JSON object that contains structured item attribute data keyed by attribute name. Catalog item attributes are available only to brand owners and conform to the related product type definitions available in the Selling Partner API for Product Type Definitions. | ItemAttributes |
| identifiers optional | Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers. | ItemIdentifiers |
| images optional | Images for an item in the Amazon catalog. All image variants are provided to brand owners. Otherwise, a thumbnail of the "MAIN" image variant is provided. | ItemImages |
| productTypes optional | Product types associated with the Amazon catalog item. | ItemProductTypes |
| salesRanks optional | Sales ranks of an Amazon catalog item. | ItemSalesRanks |
| summaries optional | Summary details of an Amazon catalog item. | ItemSummaries |
| variations optional | Variation details by marketplace for an Amazon catalog item (variation relationships). | ItemVariations |
| vendorDetails optional | Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only. | ItemVendorDetails |
ItemAsin
Amazon Standard Identification Number (ASIN) is the unique identifier for an item in the Amazon catalog.
Type : string
ItemAttributes
A JSON object that contains structured item attribute data keyed by attribute name. Catalog item attributes are available only to brand owners and conform to the related product type definitions available in the Selling Partner API for Product Type Definitions.
Type : object
ItemIdentifiers
Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.
Type : < ItemIdentifiersByMarketplace > array
ItemIdentifiersByMarketplace
Identifiers associated with the item in the Amazon catalog for the indicated Amazon marketplace.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | Amazon marketplace identifier. | string |
| identifiers required | Identifiers associated with the item in the Amazon catalog for the indicated Amazon marketplace. | < ItemIdentifier > array |
ItemIdentifier
Identifier associated with the item in the Amazon catalog, such as a UPC or EAN identifier.
| Name | Description | Schema |
|---|---|---|
| identifierType required | Type of identifier, such as UPC, EAN, or ISBN. | string |
| identifier required | Identifier. | string |
ItemImages
Images for an item in the Amazon catalog. All image variants are provided to brand owners. Otherwise, a thumbnail of the "MAIN" image variant is provided.
Type : < ItemImagesByMarketplace > array
ItemImagesByMarketplace
Images for an item in the Amazon catalog for the indicated Amazon marketplace.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | Amazon marketplace identifier. | string |
| images required | Images for an item in the Amazon catalog for the indicated Amazon marketplace. | < ItemImage > array |
ItemImage
Image for an item in the Amazon catalog.
| Name | Description | Schema |
|---|---|---|
| variant required | Variant of the image, such as MAIN or PT01. Example : "MAIN" | enum (Variant) |
| link required | Link, or URL, for the image. | string |
| height required | Height of the image in pixels. | integer |
| width required | Width of the image in pixels. | integer |
ItemProductTypes
Product types associated with the Amazon catalog item.
Type : < ItemProductTypeByMarketplace > array
ItemProductTypeByMarketplace
Product type associated with the Amazon catalog item for the indicated Amazon marketplace.
| Name | Description | Schema |
|---|---|---|
| marketplaceId optional | Amazon marketplace identifier. | string |
| productType optional | Name of the product type associated with the Amazon catalog item. Example : "LUGGAGE" | string |
ItemSalesRanks
Sales ranks of an Amazon catalog item.
Type : < ItemSalesRanksByMarketplace > array
ItemSalesRanksByMarketplace
Sales ranks of an Amazon catalog item for the indicated Amazon marketplace.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | Amazon marketplace identifier. | string |
| ranks required | Sales ranks of an Amazon catalog item for an Amazon marketplace. | < ItemSalesRank > array |
ItemSalesRank
Sales rank of an Amazon catalog item.
| Name | Description | Schema |
|---|---|---|
| title required | Title, or name, of the sales rank. | string |
| link optional | Corresponding Amazon retail website link, or URL, for the sales rank. | string |
| rank required | Sales rank value. | integer |
ItemSummaries
Summary details of an Amazon catalog item.
Type : < ItemSummaryByMarketplace > array
ItemSummaryByMarketplace
Summary details of an Amazon catalog item for the indicated Amazon marketplace.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | Amazon marketplace identifier. | string |
| brandName optional | Name of the brand associated with an Amazon catalog item. | string |
| browseNode optional | Identifier of the browse node associated with an Amazon catalog item. | string |
| colorName optional | Name of the color associated with an Amazon catalog item. | string |
| itemName optional | Name, or title, associated with an Amazon catalog item. | string |
| manufacturer optional | Name of the manufacturer associated with an Amazon catalog item. | string |
| modelNumber optional | Model number associated with an Amazon catalog item. | string |
| sizeName optional | Name of the size associated with an Amazon catalog item. | string |
| styleName optional | Name of the style associated with an Amazon catalog item. | string |
ItemVariations
Variation details by marketplace for an Amazon catalog item (variation relationships).
Type : < ItemVariationsByMarketplace > array
ItemVariationsByMarketplace
Variation details for the Amazon catalog item for the indicated Amazon marketplace.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | Amazon marketplace identifier. | string |
| asins required | Identifiers (ASINs) of the related items. | < string > array |
| variationType required | Type of variation relationship of the Amazon catalog item in the request to the related item(s): "PARENT" or "CHILD". Example : "PARENT" | enum (VariationType) |
ItemVendorDetails
Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only.
Type : < ItemVendorDetailsByMarketplace > array
ItemVendorDetailsByMarketplace
Vendor details associated with an Amazon catalog item for the indicated Amazon marketplace.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | Amazon marketplace identifier. | string |
| brandCode optional | Brand code associated with an Amazon catalog item. | string |
| categoryCode optional | Product category associated with an Amazon catalog item. | string |
| manufacturerCode optional | Manufacturer code associated with an Amazon catalog item. | string |
| manufacturerCodeParent optional | Parent vendor code of the manufacturer code. | string |
| productGroup optional | Product group associated with an Amazon catalog item. | string |
| replenishmentCategory optional | Replenishment category associated with an Amazon catalog item. | enum (ReplenishmentCategory) |
| subcategoryCode optional | Product subcategory associated with an Amazon catalog item. | string |
ItemSearchResults
Items in the Amazon catalog and search related metadata.
| Name | Description | Schema |
|---|---|---|
| numberOfResults required | The estimated total number of products matched by the search query (only results up to the page count limit will be returned per request regardless of the number found). Note: The maximum number of items (ASINs) that can be returned and paged through is 1000. | integer |
| pagination required | If available, the nextToken and/or previousToken values required to return paginated results. | Pagination |
| refinements required | Search refinements. | Refinements |
| items required | A list of items from the Amazon catalog. | < Item > array |
Pagination
When a request produces a response that exceeds the pageSize, pagination occurs. This means the response is divided into individual pages. To retrieve the next page or the previous page, you must pass the nextToken value or the previousToken value as the pageToken parameter in the next request. When you receive the last page, there will be no nextToken key in the pagination object.
| Name | Description | Schema |
|---|---|---|
| nextToken optional | A token that can be used to fetch the next page. | string |
| previousToken optional | A token that can be used to fetch the previous page. | string |
Refinements
Search refinements.
| Name | Description | Schema |
|---|---|---|
| brands required | Brand search refinements. | < BrandRefinement > array |
| classifications required | Classification search refinements. | < ClassificationRefinement > array |
BrandRefinement
Description of a brand that can be used to get more fine-grained search results.
| Name | Description | Schema |
|---|---|---|
| numberOfResults required | The estimated number of results that would still be returned if refinement key applied. | integer |
| brandName required | Brand name. For display and can be used as a search refinement. | string |
ClassificationRefinement
Description of a classification that can be used to get more fine-grained search results.
| Name | Description | Schema |
|---|---|---|
| numberOfResults required | The estimated number of results that would still be returned if refinement key applied. | integer |
| displayName required | Display name for the classification. | string |
| classificationId required | Identifier for the classification that can be used for search refinement purposes. | string |
Variant
Variant of the image, such as MAIN or PT01.
Type : enum
| Value | Description |
|---|---|
| MAIN | Main image for the item. |
| PT01 | Other image #1 for the item. |
| PT02 | Other image #2 for the item. |
| PT03 | Other image #3 for the item. |
| PT04 | Other image #4 for the item. |
| PT05 | Other image #5 for the item. |
| PT06 | Other image #6 for the item. |
| PT07 | Other image #7 for the item. |
| PT08 | Other image #8 for the item. |
| SWCH | Swatch image for the item. |
VariationType
Type of variation relationship of the Amazon catalog item in the request to the related item(s): "PARENT" or "CHILD".
Type : enum
| Value | Description |
|---|---|
| PARENT | The Amazon catalog item in the request is a variation parent of the related item(s) indicated by ASIN. |
| CHILD | The Amazon catalog item in the request is a variation child of the related item identified by ASIN. |
ReplenishmentCategory
Replenishment category associated with an Amazon catalog item.
Type : enum
| Value | Description |
|---|---|
| ALLOCATED | Indicates non-automated purchasing of inventory that has been allocated to Amazon by the vendor. |
| BASIC_REPLENISHMENT | Indicates non-automated purchasing of inventory. |
| IN_SEASON | Indicates non-automated purchasing of inventory for seasonal items. |
| LIMITED_REPLENISHMENT | Holding queue replenishment status before an item is NEW_PRODUCT. |
| MANUFACTURER_OUT_OF_STOCK | Indicates vendor is out of stock for a longer period of time and cannot backorder. |
| NEW_PRODUCT | Indicates a new item that Amazon does not yet stock in inventory. |
| NON_REPLENISHABLE | Indicates assortment parent used for detail page display, not actual items. |
| NON_STOCKUPABLE | Indicates drop ship inventory that Amazon does not stock in its fulfillment centers. |
| OBSOLETE | Indicates item is obsolete and should not be ordered. |
| PLANNED_REPLENISHMENT | Indicates active items that should be automatically ordered. |
IncludedData
Type : enum
For use with the operation(s): searchCatalogItems
| Value | Description |
|---|---|
| identifiers | Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers. |
| images | Images for an item in the Amazon catalog. All image variants are provided to brand owners; a thumbnail of the "MAIN" image variant is provided otherwise. |
| productTypes | Product types associated with the Amazon catalog item. |
| salesRanks | Sales ranks of an Amazon catalog item. |
| summaries | Summary details of an Amazon catalog item. |
| variations | Variation details of an Amazon catalog item (variation relationships). |
| vendorDetails | Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only. |
For use with the operation(s): getCatalogItem
| Value | Description |
|---|---|
| attributes | A JSON object containing structured item attribute data keyed by attribute name. Catalog item attributes are available only to brand owners and conform to the related Amazon product type definitions available in the Selling Partner API for Product Type Definitions. |
| identifiers | Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers. |
| images | Images for an item in the Amazon catalog. All image variants are provided to brand owners. Otherwise, a thumbnail of the "MAIN" image variant is provided. |
| productTypes | Product types associated with the Amazon catalog item. |
| salesRanks | Sales ranks of an Amazon catalog item. |
| summaries | Summary details of an Amazon catalog item. |
| variations | Variation details of an Amazon catalog item (variation relationships). |
| vendorDetails | Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only. |
Updated 4 months ago