Amazon Selling Partner API - spapi.cyou

Catalog Items API v2022-04-01 reference

AmazonSPAPI

# 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 (opens new window).

# Version information

Version : 2022-04-01

# Operations

searchCatalogItems
getCatalogItem

# Paths

# searchCatalogItems

GET /catalog/2022-04-01/items

# 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
5 5

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 (opens new window).

# Parameters

Type Name Description Schema Default
Query identifiers
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) -
Query identifiersType
optional		 Type of product identifiers to search the Amazon catalog for. Note: Required when identifiers are provided. enum (IdentifiersType) -
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) "[\"summaries\"]"
Query locale
optional		 Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace. string -
Query sellerId
optional		 A selling partner identifier, such as a seller account or vendor code. Note: Required when identifiersType is SKU. string -
Query keywords
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) -
Query brandNames
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) -
Query classificationIds
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) -
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 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 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

# getCatalogItem

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

# Description

Retrieves details for an item in the Amazon catalog.

Usage Plan:

Rate (requests per second) Burst
5 5

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 (opens new window).

# Parameters

Type Name Description Schema Default
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) "[\"summaries\"]"
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-RequestId (string):Unique request reference identifier.		 ErrorList
415 The request payload is in an unsupported format.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.		 ErrorList
429 The frequency of requests was greater than allowed.
Headers:
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-RequestId (string):Unique request reference identifier.		 ErrorList
503 Temporary 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.

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

Name Description Schema
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.

Name Description Schema
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.

Name Description Schema
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.

Name Description Schema
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.

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.

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

Name Description Schema
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.

Name Description Schema
websiteDisplayGroup
required		 Name of the website display group 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

# 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
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		 Identifier of the website display group associated with an Amazon catalog item. string
websiteDisplayGroupName
optional		 Display 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.

Name Description Schema
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.

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

# ItemRelationship

Relationship details for an Amazon catalog item.

Name Description Schema
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.

Name Description Schema
displayName
optional		 Display name of the product category or subcategory string
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.

Name Description Schema
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.

Name Description Schema
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.

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.

# IdentifiersType

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

Type : enum

Value Description
ASIN Amazon Standard Identification Number.
EAN European Article Number.
GTIN Global Trade Item Number.
ISBN International Standard Book Number.
JAN Japanese Article Number.
MINSAN Minsan Code.
SKU Stock Keeping Unit, a seller-specified identifier for an Amazon listing. Note: Must be accompanied by sellerId.
UPC Universal Product Code.

# ItemClassification

Classification type associated with the Amazon catalog item.

Type : enum

Value Description
BASE_PRODUCT Represents a standard standalone or a variation child item in the Amazon catalog.
OTHER Represents an item in the Amazon catalog that is not BASE_PRODUCT, PRODUCT_BUNDLE, or VARIATION_PARENT.
PRODUCT_BUNDLE Represents a parent Amazon catalog item representing a bundle of items.
VARIATION_PARENT Represents a parent Amazon catalog item grouping child items into a variation family.

# Type

Type of relationship.

Type : enum

Value Description
VARIATION The Amazon catalog item in the request is a variation parent or variation child of the related item(s) indicated by ASIN.
PACKAGE_HIERARCHY The 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

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): getCatalogItem

Value Description
attributes A 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.
dimensions Dimensions for an item in the Amazon catalog.
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.
productTypes Product types associated with the Amazon catalog item.
relationships Relationship details of an Amazon catalog item (for example, variations).
salesRanks Sales ranks of an Amazon catalog item.
summaries Summary details of an Amazon catalog item. Refer to the "attributes" of an Amazon catalog item for more details.
vendorDetails Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only.

For use with the operation(s): searchCatalogItems

Value Description
attributes A 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.
dimensions Dimensions for an item in the Amazon catalog.
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.
productTypes Product types associated with the Amazon catalog item.
relationships Relationship details of an Amazon catalog item (for example, variations).
salesRanks Sales ranks of an Amazon catalog item.
summaries Summary details of an Amazon catalog item. Refer to the attributes of an Amazon catalog item for more details.
vendorDetails Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only.

Easy Ship API v2022-03-23