searchCatalogItems

get https://sellingpartnerapi-na.amazon.com/catalog/2020-12-01/items

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.

Query Params

keywords

array of strings

required

A comma-delimited list of words or item identifiers to search the Amazon catalog for.

keywords*

marketplaceIds

array of strings

required

length ≤ 1

A comma-delimited list of Amazon marketplace identifiers for the request.

marketplaceIds*

includedData

array of strings

Defaults to summaries

A comma-delimited list of data sets to include in the response. Default: summaries.

Show Details

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.

includedData

brandNames

array of strings

A comma-delimited list of brand names to limit the search to.

brandNames

classificationIds

array of strings

A comma-delimited list of classification identifiers to limit the search to.

classificationIds

pageSize

integer

≤ 20

Defaults to 10

Number of results to be returned per page.

pageToken

string

A token to fetch a certain page when there are multiple pages worth of results.

keywordsLocale

string

The language the keywords are provided in. Defaults to the primary locale of the marketplace.

locale

string

Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace.

Responses

Response body

object

numberOfResults

integer

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.

pagination

object

required

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.

nextToken

string

A token that can be used to fetch the next page.

previousToken

string

A token that can be used to fetch the previous page.

refinements

object

required

Search refinements.

brands

array of objects

required

Brand search refinements.

brands*

object

numberOfResults

integer

required

The estimated number of results that would still be returned if refinement key applied.

brandName

string

required

Brand name. For display and can be used as a search refinement.

classifications

array of objects

required

Classification search refinements.

classifications*

object

numberOfResults

integer

required

The estimated number of results that would still be returned if refinement key applied.

displayName

string

required

Display name for the classification.

classificationId

string

required

Identifier for the classification that can be used for search refinement purposes.

items

array of objects

required

A list of items from the Amazon catalog.

items*

object

asin

string

required

Amazon Standard Identification Number (ASIN) is the unique identifier for an item in the Amazon catalog.

attributes

object

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.

Has additional fields

identifiers

array of objects

Identifiers associated with the item in the Amazon catalog, such as UPC and EAN identifiers.

identifiers

object

marketplaceId

string

required

Amazon marketplace identifier.

identifiers

array of objects

required

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

identifiers*

object

identifierType

string

required

Type of identifier, such as UPC, EAN, or ISBN.

identifier

string

required

Identifier.

images

array of objects

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.

images

object

marketplaceId

string

required

Amazon marketplace identifier.

images

array of objects

required

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

images*

object

variant

string

required

Variant of the image, such as MAIN or PT01.

MAIN PT01 PT02 PT03 PT04 PT05 PT06 PT07 PT08 SWCH

Show Details

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.

link

string

required

Link, or URL, for the image.

height

integer

required

Height of the image in pixels.

width

integer

required

Width of the image in pixels.

productTypes

array of objects

Product types associated with the Amazon catalog item.

productTypes

object

marketplaceId

string

Amazon marketplace identifier.

productType

string

Name of the product type associated with the Amazon catalog item.

salesRanks

array of objects

Sales ranks of an Amazon catalog item.

salesRanks

object

marketplaceId

string

required

Amazon marketplace identifier.

ranks

array of objects

required

Sales ranks of an Amazon catalog item for an Amazon marketplace.

ranks*

object

title

string

required

Title, or name, of the sales rank.

link

string

Corresponding Amazon retail website link, or URL, for the sales rank.

rank

integer

required

Sales rank value.

summaries

array of objects

Summary details of an Amazon catalog item.

summaries

object

marketplaceId

string

required

Amazon marketplace identifier.

brandName

string

Name of the brand associated with an Amazon catalog item.

browseNode

string

Identifier of the browse node associated with an Amazon catalog item.

colorName

string

Name of the color associated with an Amazon catalog item.

itemName

string

Name, or title, associated with an Amazon catalog item.

manufacturer

string

Name of the manufacturer associated with an Amazon catalog item.

modelNumber

string

Model number associated with an Amazon catalog item.

sizeName

string

Name of the size associated with an Amazon catalog item.

styleName

string

Name of the style associated with an Amazon catalog item.

variations

array of objects

Variation details by marketplace for an Amazon catalog item (variation relationships).

variations

object

marketplaceId

string

required

Amazon marketplace identifier.

asins

array of strings

required

Identifiers (ASINs) of the related items.

asins*

variationType

string

required

Type of variation relationship of the Amazon catalog item in the request to the related item(s): "PARENT" or "CHILD".

PARENT CHILD

Show Details

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.

vendorDetails

array of objects

Vendor details associated with an Amazon catalog item. Vendor details are available to vendors only.

vendorDetails

object

marketplaceId

string

required

Amazon marketplace identifier.

brandCode

string

Brand code associated with an Amazon catalog item.

categoryCode

string

Product category associated with an Amazon catalog item.

manufacturerCode

string

Manufacturer code associated with an Amazon catalog item.

manufacturerCodeParent

string

Parent vendor code of the manufacturer code.

productGroup

string

Product group associated with an Amazon catalog item.

replenishmentCategory

string

Replenishment category associated with an Amazon catalog item.

ALLOCATED BASIC_REPLENISHMENT IN_SEASON LIMITED_REPLENISHMENT MANUFACTURER_OUT_OF_STOCK NEW_PRODUCT NON_REPLENISHABLE NON_STOCKUPABLE OBSOLETE PLANNED_REPLENISHMENT

Show Details

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.

subcategoryCode

string

Product subcategory associated with an Amazon catalog item.

Headers

object

x-amzn-RateLimit-Limit

string

Your rate limit (requests per second) for this operation.

x-amzn-RequestId

string

Unique request reference identifier.

Language


xxxxxxxxxx
1
curl --request GET \
2
     --url 'https://sellingpartnerapi-na.amazon.com/catalog/2020-12-01/items?includedData=summaries&pageSize=10' \
3
     --header 'accept: application/json'


xxxxxxxxxx
121
}
1
{
2
  "numberOfResults": 3097,
3
  "pagination": {
4
    "nextToken": "xsdflkj324lkjsdlkj3423klkjsdfkljlk2j34klj2l3k4jlksdjl234",
5
    "previousToken": "ilkjsdflkj234lkjds234234lkjl234lksjdflkj234234lkjsfsdflkj333d"
6
  },
7
  "refinements": {
8
    "brands": [
9
      {
10
        "numberOfResults": 1,
11
        "brandName": "Truly Teague"
12
      },
13
      {
14
        "numberOfResults": 20,
15
        "brandName": "Always Awesome Apparel"
16
      }
17
    ],
18
    "categories": [
19
      {
20
        "numberOfResults": 300,
21
        "displayName": "Electronics",
22
        "classificationId": "493964"
23
      },
24
      {
25
        "numberOfResults": 4000,

200Success.

400Request has missing or invalid parameters and cannot be parsed.

403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.

404The resource specified does not exist.

413The request size exceeded the maximum accepted size.

415The request payload is in an unsupported format.

429The frequency of requests was greater than allowed.

500An unexpected condition occurred that prevented the server from fulfilling the request.

503Temporary overloading or maintenance of the server.