Search catalog items

Learn how to search for and return a list of Amazon catalog items and associated information for the given ASINs, product identifiers, or keywords. For searches that return lists that have multiple pages, learn how to retrieve subsequent and previous pages.

Prerequisites

To complete this tutorial, you need:

• Authorization from the Selling Partner for whom you are making calls. Go to Authorizing Selling Partner API applications for more information.

• Approval for the Product Listing role in your developer profile.

• The Product Listing role selected in the App registration page for your application.

🚧

Handling generic JSON schemas in client libraries

If you have generated a client library, it is important to note that Swagger Codegen generates types based on properties defined in the Swagger models, and that Swagger Codegen will produce empty or incomplete types when an object is defined with additionalProperties: true. To handle such objects, use the --import-mappings command-line parameter to map these objects to a generic JSON object type or a custom object type of your choosing.

Example Swagger Codegen input parameters:

C#: --import-mappings ItemAttributes=Newtonsoft.Json.Linq.JObject
Java: --import-mappings ItemAttributes=com.google.gson.JsonObject

Step 1. Search for items

Call the searchCatalogItems operation. This returns the first page of results.

Step 2. Check for results beyond the first page

Check the pagination object in the response to searchCatalogItems. When the response does not exceed the pageSize, there is no pagination, so there is no nextToken or previousToken.

📘

Note

Page tokens are special values that are decoded to determine which page is requested and how many pages are before or after. Page tokens are specific to the request. You cannot change the page size on the next request when using a page token.

Even though there can be more than 1,000 ASINs that match the search criteria, the maximum number of results that can be returned and paged through is limited to 1,000. For example, if the caller sets the pageSize to 10, the maximum number of possible pages is 100.

Example of a searchCatalogItems response that does not exceed the pageSize

"pagination": {
},

Examples of a searchCatalogItems responses that exceed the pageSize

If the pagination object includes a nextToken value, there are more results beyond the first page.

"pagination": {
  "nextToken": "XXXXXX"
},

For the last page, there is no next page, so there is no nextToken:

"pagination": {
  "previousToken": "XXXXXX"
},

For all other pages:

"pagination": {
  "nextToken": "XXXXXX",
  "previousToken": "XXXXXX"
},

Step 3a. Go to the next page of results

To retrieve the next page, pass the nextToken value as the pageToken parameter in the next request.

Step 3b. Go to the previous page of results

To retrieve the previous page, pass the previousToken value as the pageToken parameter in the next request.