HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Catalog Items API v2022-04-01 Use Case Guide

How to use the Catalog Items API.

API Version: 2022-04-01

What is the Catalog Items API?

Using the Selling Partner API for Catalog Items (Catalog Items API), you can retrieve information about items in the Amazon catalog. Refer to the Catalog Items API Reference for details about API operations and associated data types and schemas.

Key Features

  • Retrieve detailed item information: The Catalog Items API provides details about items in the Amazon catalog, such as:

    • Summarized item details
    • Attributes
    • Browse classifications
    • Dimensions
    • Product identifiers
    • Images
    • Sales rankings
    • Relationships

Vendors can retrieve additional vendor-specific details.

  • Search by identifiers or keywords. The Catalog Items API allows you to search for Amazon catalog items and associated information either by identifiers (such as UPC or EAN identifiers, up-to 20 per request) or by keywords. The same item details are available when performing a search query or when retrieving items explicitly by ASIN.

Terminology

  • ASIN: Amazon Standard Identification Number that identifies an item in the Amazon catalog.

  • SKU: Selling partner-supplied SKU that identifies a seller or vendor listing. Data from one or more selling partner listings are reconciled into items in the Amazon catalog.

  • Variation: Variations are a type of relationship between Amazon catalog items that group items that vary by color, size, or other attributes. A parent Amazon catalog item is used to group the child items into the variation family. For example, one shirt can be offered in multiple sizes and colors. In this scenario, each distinct size and color combination is represented as its own item in the Amazon catalog with a parent item that groups them to provide a single detail page on the Amazon retail websites.

🚧

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

Tutorial: Retrieve details for an individual item in the Amazon catalog by its identifier (ASIN)

Use this tutorial to retrieve information about an item in the Amazon catalog for the given ASIN and marketplaces.

Prerequisites

To complete this tutorial, you will 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.

Step 1: Get information about a catalog item

Call the getCatalogItem operation, passing the following parameters:

Path Parameters

Parameter Type Example Description Required
asin string XXXXXXXXXX Amazon Standard Identification Number for the item of interest. Yes

Query Parameters

Parameter Type Example Description Required
marketplaceIds < string > array(csv) ATVPDKIKX0DER A comma-delimited list of Amazon marketplace identifiers.

Refer to Marketplace IDs for a list of Amazon marketplace identifiers. 		Yes
includedData < enum (IncludedData) > array(csv) summaries A comma-delimited list of item details to request. If none are specified, will default to returning summaries data.
  • attributes - Listable item attributes. Available to the brand owner of the item. Contains all listable item attributes present on the item for its particular product type. Refer to the Product Type Definitions API for more information about retrieving JSON Schemas that describe the format of the attributes returned.
  • classifications - Browse classifications (also called *nodes* or *product categories*).
  • dimensions - Item and package dimensions.
  • identifiers - External item identifiers such as EAN, UPC, ISBN.
  • images - Product images. Each product image will contain the name of the image variant, resolution, and a link to download the image.
  • productTypes - Item product type. The attributes and data requirements for an item are defined by its product type, which can be retrieved using the Product Type Definitions API.
  • relationships - Item relationships data. Contains lists of ASINs representing the parent or child items related to this item.
  • salesRanks - Item sales ranking data. Each sales ranking will contain the name of the category, the item's ranking, and a link to the sales ranking page on the retail website.
  • summaries - Summary of item data. Basic attributes such as the item name, manufacturer, and brand.
  • vendorDetails - Item vendor data. Available to vendors. Contains item replenishment, brand, and manufacturer information.
No
locale string en_US Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace. No

Example Request:

GET https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items/XXXXXXXXXX
  ?marketplaceIds=ATVPDKIKX0DER
  &includedData=attributes,classifications,dimensions,identifiers,images,productTypes,salesRanks,summaries,relationships,vendorDetails

Response

A successful response includes the following:

Name Type Description
asin ItemAsin The requested ASIN.
attributes ItemAttributes A JSON object containing detailed catalog item data. Values from multiple marketplaces are rolled up into a list under each attribute name.

Refer to the Product Type Definitions API Use Case Guide for more information.
classifications ItemBrowseClassifications Browse classifications (also called *nodes* or *product categories*).
dimensions ItemDimensions Normalized item and package dimensions.
identifiers ItemIdentifiers External identifiers such as UPC, EAN, if applicable.
images ItemImages Image data for the item.
productTypes ItemProductTypes The product type of the item within the Amazon catalog. Refer to the Product Type Definitions API for more information.
ranks ItemSalesRanks The sales ranking data for the item in every category it is tracked in.
relationships ItemRelationships Lists of ASINs representing the parent or child items related to this item.
summaries ItemSummaries Summary of item data.
vendorDetails ItemVendorDetails Detailed vendor information for this product.

Example Response:

{
  "asin": "B07N4M94X4",
  "attributes": {
    "total_hdmi_ports": [
      {
        "value": 4,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "resolution": [
      {
        "language_tag": "en_US",
        "value": "4K",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_weight": [
      {
        "unit": "pounds",
        "value": 107.6,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "product_subcategory": [
      {
        "value": "50400120",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "bullet_point": [
      {
        "language_tag": "en_US",
        "value": "SMART TV WITH UNIVERSAL GUIDE: Simple on-screen Guide is an easy way to find streaming content and live TV shows",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "100% COLOR VOLUME WITH QUANTUM DOTS: Powered by Quantum dots, Samsung’s 4K QLED TV offers over a billion shades of brilliant color and 100% color volume for exceptional depth of detail that will draw you in to the picture for the best 4K TV experience",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "QUANTUM PROCESSOR 4K: Intelligently powered processor instantly upscales content to 4K for sharp detail and refined color",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "QUANTUM HDR 4X: 4K depth of detail with high dynamic range powered by HDR10+ delivers the lightest to darkest colors, scene by scene, for amazing picture realism",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "AMBIENT MODE: Customizes and complements your living space by turning a blank screen of this big screen TV into enticing visuals including décor, info, photos and artwork",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "SMART TV FEATURES: OneRemote to control all compatible devices, Bixby voice command, on-screen universal guide, SmartThings to control compatible home appliances and devices, smart speaker expandability with Alexa and Google Assistant compatibility, and more",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_dimensions": [
      {
        "width": {
          "unit": "inches",
          "value": 72.4
        },
        "length": {
          "unit": "inches",
          "value": 2.4
        },
        "height": {
          "unit": "inches",
          "value": 41.4
        },
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "brand": [
      {
        "language_tag": "en_US",
        "value": "SAMSUNG",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "control_method": [
      {
        "value": "voice",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_package_dimensions": [
      {
        "length": {
          "unit": "centimeters",
          "value": 26.67
        },
        "width": {
          "unit": "centimeters",
          "value": 121.92
        },
        "height": {
          "unit": "centimeters",
          "value": 203.2
        },
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "image_aspect_ratio": [
      {
        "language_tag": "en_US",
        "value": "16:9",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "part_number": [
      {
        "value": "QN82Q60RAFXZA",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "includes_remote": [
      {
        "value": true,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "style": [
      {
        "language_tag": "en_US",
        "value": "TV only",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_type_name": [
      {
        "language_tag": "en_US",
        "value": "TV",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "battery": [
      {
        "cell_composition": [
          {
            "value": "alkaline"
          }
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "image_contrast_ratio": [
      {
        "language_tag": "en_US",
        "value": "QLED 4K",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "manufacturer": [
      {
        "language_tag": "en_US",
        "value": "Samsung",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "number_of_boxes": [
      {
        "value": 1,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "total_usb_ports": [
      {
        "value": 2,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "model_number": [
      {
        "value": "QN82Q60RAFXZA",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "supplier_declared_dg_hz_regulation": [
      {
        "value": "not_applicable",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "num_batteries": [
      {
        "quantity": 2,
        "type": "aaa",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "california_proposition_65": [
      {
        "compliance_type": "on_product_combined_cancer_reproductive",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "compliance_type": "chemical",
        "chemical_names": [
          "di_2_ethylhexyl_phthalate_dehp"
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "display": [
      {
        "resolution_maximum": [
          {
            "unit": "pixels",
            "language_tag": "en_US",
            "value": "3840 x 2160"
          }
        ],
        "size": [
          {
            "unit": "inches",
            "value": 82
          }
        ],
        "type": [
          {
            "language_tag": "en_US",
            "value": "QLED"
          }
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_name": [
      {
        "language_tag": "en_US",
        "value": "Samsung QN82Q60RAFXZA Flat 82-Inch QLED 4K Q60 Series (2019) Ultra HD Smart TV with HDR and Alexa Compatibility",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "list_price": [
      {
        "currency": "USD",
        "value": 3799.99,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "batteries_required": [
      {
        "value": false,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "includes_rechargable_battery": [
      {
        "value": false,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "product_site_launch_date": [
      {
        "value": "2019-03-11T08:00:01.000Z",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "product_category": [
      {
        "value": "50400100",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "batteries_included": [
      {
        "value": false,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "connectivity_technology": [
      {
        "language_tag": "en_US",
        "value": "Bluetooth",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "USB",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Wireless",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "HDMI",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "included_components": [
      {
        "language_tag": "en_US",
        "value": "QLED Standard Smart Remote",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Power Cable",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Stand",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Samsung Smart Control",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "specification_met": [
      {
        "language_tag": "en_US",
        "value": "",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "parental_control_technology": [
      {
        "value": "V-Chip",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "power_consumption": [
      {
        "unit": "watts",
        "value": 120,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "cpsia_cautionary_statement": [
      {
        "value": "no_warning_applicable",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_type_keyword": [
      {
        "value": "qled-televisions",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "number_of_items": [
      {
        "value": 1,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "warranty_description": [
      {
        "language_tag": "en_US",
        "value": "1 year manufacturer",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "max_resolution": [
      {
        "unit": "pixels",
        "value": 8.3,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "color": [
      {
        "language_tag": "en_US",
        "value": "Black",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "screen_surface_description": [
      {
        "language_tag": "en_US",
        "value": "Flat",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_package_weight": [
      {
        "unit": "kilograms",
        "value": 62.142,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "speaker_type": [
      {
        "language_tag": "en_US",
        "value": "2CH",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "supported_internet_services": [
      {
        "language_tag": "en_US",
        "value": "Amazon Instant Video",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "YouTube",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Netflix",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Hulu",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Browser",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "tuner_technology": [
      {
        "language_tag": "en_US",
        "value": "Analog Tuner",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "controller_type": [
      {
        "language_tag": "en_US",
        "value": "SmartThings",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Voice Control",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "special_feature": [
      {
        "language_tag": "en_US",
        "value": "100% Color Volume with Quantum Dot; Quantum Processor 4K; Ambient Mode; Quantum HDR 4X; Real Game Enhancer",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "wireless_communication_technology": [
      {
        "language_tag": "en_US",
        "value": "Wi-Fi::Wi-Fi Direct::Bluetooth",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "model_year": [
      {
        "value": 2019,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "power_source_type": [
      {
        "language_tag": "en_US",
        "value": "Corded Electric",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "street_date": [
      {
        "value": "2019-03-21T00:00:01Z",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "mounting_type": [
      {
        "language_tag": "en_US",
        "value": "Table Mount",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "Wall Mount",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "refresh_rate": [
      {
        "unit": "hertz",
        "language_tag": "en_US",
        "value": "120",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ]
  },
  "classifications": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "classifications": [
        {
          "displayName": "QLED TVs",
          "classificationId": "21489946011",
          "parent": {
            "displayName": "Televisions",
            "classificationId": "172659",
            "parent": {
              "displayName": "Television & Video",
              "classificationId": "1266092011",
              "parent": {
                "displayName": "Electronics",
                "classificationId": "172282"
              }
            }
          }
        }
      ]
    }
  ],  
  "dimensions": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "item": {
        "height": {
          "unit": "inches",
          "value": 41.4
        },
        "length": {
          "unit": "inches",
          "value": 2.4
        },
        "weight": {
          "unit": "pounds",
          "value": 107.6
        },
        "width": {
          "unit": "inches",
          "value": 72.4
        }
      },
      "package": {
        "height": {
          "unit": "inches",
          "value": 10.49999998929
        },
        "length": {
          "unit": "inches",
          "value": 79.9999999184
        },
        "weight": {
          "unit": "kilograms",
          "value": 62.142
        },
        "width": {
          "unit": "inches",
          "value": 47.99999995104
        }
      }
    }
  ],
  "identifiers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "identifiers": [
        {
          "identifier": "0887276302195",
          "identifierType": "EAN"
        },
        {
          "identifier": "00887276302195",
          "identifierType": "GTIN"
        },
        {
          "identifier": "887276302195",
          "identifierType": "UPC"
        }
      ]
    }
  ],
  "images": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "images": [
        {
          "variant": "MAIN",
          "link": "https://m.media-amazon.com/images/I/91uohwV+k3L.jpg",
          "height": 1707,
          "width": 2560
        },
        {
          "variant": "MAIN",
          "link": "https://m.media-amazon.com/images/I/51DZzp3w3vL.jpg",
          "height": 333,
          "width": 500
        },
        {
          "variant": "PT01",
          "link": "https://m.media-amazon.com/images/I/81w2rTVShlL.jpg",
          "height": 2560,
          "width": 2560
        },
        {
          "variant": "PT01",
          "link": "https://m.media-amazon.com/images/I/41Px9eq9tkL.jpg",
          "height": 500,
          "width": 500
        },
        {
          "variant": "PT02",
          "link": "https://m.media-amazon.com/images/I/51NTNhdhPyL.jpg",
          "height": 375,
          "width": 500
        },
        {
          "variant": "PT03",
          "link": "https://m.media-amazon.com/images/I/51o4zpL+A3L.jpg",
          "height": 375,
          "width": 500
        },
        {
          "variant": "PT04",
          "link": "https://m.media-amazon.com/images/I/71ux2k9GAZL.jpg",
          "height": 1000,
          "width": 1000
        },
        {
          "variant": "PT04",
          "link": "https://m.media-amazon.com/images/I/61UUX63yw1L.jpg",
          "height": 500,
          "width": 500
        },
        {
          "variant": "PT05",
          "link": "https://m.media-amazon.com/images/I/61LwHkljX-L.jpg",
          "height": 1000,
          "width": 1000
        },
        {
          "variant": "PT05",
          "link": "https://m.media-amazon.com/images/I/51wJTQty3PL.jpg",
          "height": 500,
          "width": 500
        },
        {
          "variant": "PT06",
          "link": "https://m.media-amazon.com/images/I/61uvoB4VvoL.jpg",
          "height": 1000,
          "width": 1000
        },
        {
          "variant": "PT06",
          "link": "https://m.media-amazon.com/images/I/51ZexIO628L.jpg",
          "height": 500,
          "width": 500
        },
        {
          "variant": "PT07",
          "link": "https://m.media-amazon.com/images/I/7121MGd2ncL.jpg",
          "height": 1000,
          "width": 1000
        },
        {
          "variant": "PT07",
          "link": "https://m.media-amazon.com/images/I/61QK+JBMrGL.jpg",
          "height": 500,
          "width": 500
        },
        {
          "variant": "PT08",
          "link": "https://m.media-amazon.com/images/I/61ECcGlG4IL.jpg",
          "height": 1080,
          "width": 1920
        },
        {
          "variant": "PT08",
          "link": "https://m.media-amazon.com/images/I/31TxwfqvB5L.jpg",
          "height": 281,
          "width": 500
        },
        {
          "variant": "PT09",
          "link": "https://m.media-amazon.com/images/I/41B5vgmp4IL.jpg",
          "height": 375,
          "width": 500
        },
        {
          "variant": "PT10",
          "link": "https://m.media-amazon.com/images/I/51S5IY3AV0L.jpg",
          "height": 375,
          "width": 500
        },
        {
          "variant": "PT11",
          "link": "https://m.media-amazon.com/images/I/41-6bmPtUlL.jpg",
          "height": 375,
          "width": 500
        },
        {
          "variant": "PT12",
          "link": "https://m.media-amazon.com/images/I/41s9Q6gWJ7L.jpg",
          "height": 448,
          "width": 500
        },
        {
          "variant": "PT13",
          "link": "https://m.media-amazon.com/images/I/519nG0mRzuL.jpg",
          "height": 314,
          "width": 500
        },
        {
          "variant": "PT14",
          "link": "https://m.media-amazon.com/images/I/71sHhrGMc7L.jpg",
          "height": 1097,
          "width": 1500
        },
        {
          "variant": "PT14",
          "link": "https://m.media-amazon.com/images/I/41CH6gKtU5L.jpg",
          "height": 366,
          "width": 500
        },
        {
          "variant": "PT15",
          "link": "https://m.media-amazon.com/images/I/21-s7QYrTxL.jpg",
          "height": 500,
          "width": 175
        },
        {
          "variant": "EEGL",
          "link": "https://m.media-amazon.com/images/I/61i3dsKD09L.jpg",
          "height": 1375,
          "width": 370
        },
        {
          "variant": "EEGL",
          "link": "https://m.media-amazon.com/images/I/41E7ku-qdGL.jpg",
          "height": 500,
          "width": 135
        },
        {
          "variant": "EGUS",
          "link": "https://m.media-amazon.com/images/I/61i3dsKD09L.jpg",
          "height": 1375,
          "width": 370
        },
        {
          "variant": "EGUS",
          "link": "https://m.media-amazon.com/images/I/41E7ku-qdGL.jpg",
          "height": 500,
          "width": 135
        }
      ]
    }
  ],
  "productTypes": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "productType": "TELEVISION"
    }
  ],
  "salesRanks": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "classificationRanks": [
        {
          "classificationId": "21489946011",
          "title": "QLED TVs",
          "link": "http://www.amazon.com/gp/bestsellers/electronics/21489946011",
          "rank": 113
        }
      ],
      "displayGroupRanks": [
        {
          "websiteDisplayGroup": "ce_display_on_website",
          "title": "Electronics",
          "link": "http://www.amazon.com/gp/bestsellers/electronics",
          "rank": 72855
        }
      ]
    }
  ],
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "brand": "SAMSUNG",
      "browseClassification": {
        "displayName": "QLED TVs",
        "classificationId": "21489946011"
      },
      "color": "Black",
      "itemClassification": "BASE_PRODUCT",
      "itemName": "Samsung QN82Q60RAFXZA Flat 82-Inch QLED 4K Q60 Series (2019) Ultra HD Smart TV with HDR and Alexa Compatibility",
      "manufacturer": "Samsung",
      "modelNumber": "QN82Q60RAFXZA",
      "packageQuantity": 1,
      "partNumber": "QN82Q60RAFXZA",
      "size": "82-Inch",
      "style": "TV only",
      "websiteDisplayGroup": "ce_display_on_website"
    }
  ],
  "relationships": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "relationships": [
        {
          "type": "VARIATION",
          "parentAsins": [
            "B08J7TQ9FL"
          ],
          "variationTheme": {
            "attributes": [
              "color",
              "size"
            ],
            "theme": "SIZE_NAME/COLOR_NAME"
          }
        }
      ]
    }
  ],
  "vendorDetails": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "brandCode": "SAMF9",
      "manufacturerCode": "SAMF9",
      "manufacturerCodeParent": "SAMF9",
      "productCategory": {
        "displayName": "Televisions",
        "value": "50400100"
      },
      "productGroup": "Home Entertainment",
      "productSubcategory": {
        "displayName": "Plasma TVs",
        "value": "50400120"
      },
      "replenishmentCategory": "OBSOLETE"
    }
  ]
}

Tutorial: Search for one or more items by ASINs or product identifiers

Use this tutorial to retrieve information about multiple items in the Amazon catalog for the supplied ASINs or product identifiers.

Prerequisites

To complete this tutorial, you will 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.

Step 1: Search for items

Call the searchCatalogItems operation with the following parameters:

Query parameters

Parameter Type Example Description Required
identifiers < string > array(csv) 0887276302195 A comma-delimited list of product identifiers to search the Amazon catalog for. Note: Cannot be used with keywords. No
identifiersType string ISBN Type of product identifiers to search the Amazon catalog for. Note: Required when identifiers are provided.
  • 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
  • UPC - Unique Product Codes
 No
marketplaceIds < string > array(csv) ATVPDKIKX0DER A comma-delimited list of Amazon marketplace identifiers for the request. Yes
includedData < enum (IncludedData) > array(csv) summaries A comma-delimited list of item details to request. If none are specified, will default to returning summaries data.
  • attributes - Listable item attributes. Available to the brand owner of the item. Contains all listable item attributes present on the item for its particular product type. Refer to the Product Type Definitions API for more information about retrieving JSON Schemas that describe the format of the attributes returned.
  • classifications - Browse classifications (also called *nodes* or *product categories*).
  • dimensions - Item and package dimensions.
  • identifiers - External item identifiers such as EAN, UPC, ISBN.
  • images - Product images. Each product image will contain the name of the image variant, resolution, and a link to download the image.
  • productTypes - Item product type. The attributes and data requirements for an item are defined by its product type, which can be retrieved using the Product Type Definitions API.
  • relationships - Item relationships data. Contains lists of ASINs representing the parent or child items related to this item.
  • salesRanks - Item sales ranking data. Each sales ranking will contain the name of the category, the item's ranking, and a link to the sales ranking page on the retail website.
  • summaries - Summary of item data. Basic attributes such as the item name, manufacturer, and brand.
  • vendorDetails - Item vendor data. Available to vendors. Contains item replenishment, brand, and manufacturer information.
No
locale string
 en_US Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace. No
sellerId string XXXXXXXXXXXX A selling partner identifier, such as a seller account or vendor code. Note: Required when identifiersType is SKU. No
pageSize integer 10 Number of results to be returned per page. No
pageToken string A token to fetch a certain page when there are multiple pages worth of results. No

Use the pageToken parameter to paginate through the results. Refer to Paging in the response to a search for items in the Amazon catalog for more information.

Example Request:

GET https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items
  ?identifiers=XXXXXXXXX,YYYYYYYY,ZZZZZZZZ
  &identifiersType=ASIN
  &marketplaceIds=ATVPDKIKX0DER

Response

A successful response includes the following:

Name Type Description
numberOfResults integer The 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.
pagination Pagination A JSON object containing one or more page tokens that can be used to fetch the next or previous page of results.
items < Item > array A list of items from the Amazon catalog. The information included for each item depends on the argument given for includedData. Refer to the Catalog Items API reference for more information.

Example Response:

{
  "numberOfResults": 3,
  "items": [
    {
      "asin": "XXXXXXXXXX",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Fred Perry",
          "color": "Wht/Brt Red/Nvy",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "Fred Perry Men's Twin Tipped Polo Shirt-M1200, WHT/BRT RED/NVY, X-Large",
          "manufacturer": "Fred Perry Men's Apparel",
          "modelNumber": "M1200",
          "packageQuantity": 1,
          "partNumber": "M1200-748",
          "size": "X-Large",
          "style": "Twin Tipped Polo Shirt-m1200",
          "websiteDisplayGroup": "apparel_display_on_website"
        }
      ]
    },
    {
      "asin": "YYYYYYYYYYY",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Universal",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "Dr. Seuss' The Lorax",
          "manufacturer": "Universal",
          "modelNumber": "ALE BOOK",
          "packageQuantity": 1,
          "partNumber": "MCAD61118810D",
          "websiteDisplayGroup": "dvd_display_on_website"
        }
      ]
    },
    {
      "asin": "ZZZZZZZZZZZ",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Muck Boot",
          "itemClassification": "VARIATION_PARENT",
          "itemName": "Muck Boot Women's Muckster 2 Ankle Snow Boot, black",
          "manufacturer": "Muck Boot",
          "style": "Muckster 2 Ankle",
          "websiteDisplayGroup": "shoes_display_on_website"
        }
      ]
    }
  ]
}

Tutorial: Search for items by keywords

Search for and return a list of Amazon catalog items and associated information either by identifier or by keywords.

Prerequisites

To successfully complete this tutorial, you must have:

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

Step 1: Search for items

Call the searchCatalogItems operation with the following parameters:

Query parameters

Parameter Type Example Description Required
brandNames < string > array(csv) Samsung A comma-delimited list of brand names to refine search results. No
classificationIds < string > array(csv) 7141124011 A comma-delimited list of classification identifiers to refine search results. No
keywords < string > array(csv) hello A comma-delimited list of keywords to search the Amazon catalog for. Note: Cannot be used with identifiers. No
keywordsLocale string en_US Locale of the keywords provided, defaults to the locale of the marketplace. No
marketplaceIds < string > array(csv) ATVPDKIKX0DER A comma-delimited list of Amazon marketplace identifiers for the request. Yes
includedData < enum (IncludedData) > array(csv) summaries A comma-delimited list of item details to request. If none are specified, will default to returning summaries data.
  • attributes - Listable item attributes. Available to the brand owner of the item. Contains all listable item attributes present on the item for its particular product type. Refer to the Product Type Definitions API for more information about retrieving JSON Schemas that describe the format of the attributes returned.
  • classifications - Browse classifications (also called *nodes* or *product categories*).
  • dimensions - Item and package dimensions.
  • identifiers - External item identifiers such as EAN, UPC, ISBN.
  • images - Product images. Each product image will contain the name of the image variant, resolution, and a link to download the image.
  • productTypes - Item product type. The attributes and data requirements for an item are defined by its product type, which can be retrieved using the Product Type Definitions API.
  • relationships - Item relationships data. Contains lists of ASINs representing the parent or child items related to this item.
  • salesRanks - Item sales ranking data. Each sales ranking will contain the name of the category, the item's ranking, and a link to the sales ranking page on the retail website.
  • summaries - Summary of item data. Basic attributes such as the item name, manufacturer, and brand.
  • vendorDetails - Item vendor data. Available to vendors. Contains item replenishment, brand, and manufacturer information.
No
locale string
 en_US Locale for retrieving localized summaries. Defaults to the primary locale of the marketplace. No
sellerId string XXXXXXXXXXXX A selling partner identifier, such as a seller account or vendor code. Note: Required when identifiersType is SKU. No
pageSize integer 10 Number of results to be returned per page. No
pageToken string Refer to the nextToken in the example response. A token to fetch a certain page when there are multiple pages worth of results. No

Use the pageToken parameter to paginate through the results. Refer to Paging in the response to a search for items in the Amazon catalog for more information.

Request example:

GET https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items
  ?keywords=hello
  &marketplaceIds={{marketplaceIds}}
  &includedData=summaries
  &pageSize=10

Response

A successful response includes the following:

Name Type Description
numberOfResults integer The 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.
items < Item > array A list of items from the Amazon catalog. The information included for each item depends on the argument given for includedData. Refer to the Catalog Items API reference for more information.
pagination Pagination A JSON object containing one or more page tokens that can be used to fetch the next or previous page of results.
refinements Refinements A JSON object containing brand and classification search refinements.

Example Response:

{
  "numberOfResults": 1000,
  "pagination": {
    "nextToken": "9HkIVcuuPmX_bm51o3-igBfN45pxW4Ru7ElIM6GCECYCuXJKzT26f5Rj4j72myj91jtjou695yNwt_JvE7qiRtfLOKtyb2IDTpSxcFmiJaztoxrP6fPkv2x86yf7CWqwS7VtDkxYifP8CHvJEnH2oh1l1vj7KQoFIa7pWiOPHyaYWP7sBE9Fg7cGN2wE0an5ePw96h6ZL7m6olRxFOcqTWNanEVRjipq"
  },
  "refinements": {
    "brands": [
      {
        "numberOfResults": 328,
        "brandName": "Hello Kitty"
      },
      {
        "numberOfResults": 139,
        "brandName": "Brand TOTOX"
      },
      {
        "numberOfResults": 101,
        "brandName": "Sanrio"
      },
      {
        "numberOfResults": 79,
        "brandName": "Vans"
      },
      {
        "numberOfResults": 73,
        "brandName": "Commonwealth Editions"
      },
      {
        "numberOfResults": 42,
        "brandName": "Webstore"
      },
      {
        "numberOfResults": 38,
        "brandName": "Unknown"
      },
      {
        "numberOfResults": 38,
        "brandName": "Web Store"
      },
      {
        "numberOfResults": 37,
        "brandName": "FOCO"
      },
      {
        "numberOfResults": 30,
        "brandName": "Skinit"
      }
    ],
    "classifications": [
      {
        "numberOfResults": 859,
        "displayName": "Books",
        "classificationId": "1000"
      },
      {
        "numberOfResults": 595,
        "displayName": "Clothing, Shoes & Jewelry",
        "classificationId": "7141124011"
      },
      {
        "numberOfResults": 371,
        "displayName": "Home & Kitchen",
        "classificationId": "1063498"
      },
      {
        "numberOfResults": 233,
        "displayName": "Toys & Games",
        "classificationId": "165795011"
      },
      {
        "numberOfResults": 197,
        "displayName": "CDs & Vinyl",
        "classificationId": "301668"
      },
      {
        "numberOfResults": 156,
        "displayName": "Baby Products",
        "classificationId": "165797011"
      },
      {
        "numberOfResults": 153,
        "displayName": "Everything Else",
        "classificationId": "10304191"
      },
      {
        "numberOfResults": 134,
        "displayName": "Electronics",
        "classificationId": "493964"
      },
      {
        "numberOfResults": 125,
        "displayName": "Sports & Outdoors",
        "classificationId": "3375301"
      },
      {
        "numberOfResults": 123,
        "displayName": "Movies & TV",
        "classificationId": "2625374011"
      }
    ]
  },
  "items": [
    {
      "asin": "B0013OMKRI",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "HELLO KITTY KT2052A Alarm Clock Radio with Night Light (Discontinued by Manufacturer)",
          "manufacturer": "HELLO KITTY",
          "modelNumber": "KT2052A",
          "packageQuantity": 1,
          "partNumber": "KT2052A",
          "websiteDisplayGroup": "ce_display_on_website"
        }
      ]
    },
    {
      "asin": "B0015ESWHI",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "HELLO KITTY KT2053 AM/FM Stereo Alarm Clock Radio with Top Loading CD Player",
          "manufacturer": "HELLO KITTY",
          "modelNumber": "KT2053",
          "packageQuantity": 1,
          "partNumber": "KT2053",
          "websiteDisplayGroup": "ce_display_on_website"
        }
      ]
    },
    {
      "asin": "B009NIYBCS",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "color": "Pink/White",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "Hello Kitty Ladies Golf Glove Set, Pink/White, 20cm",
          "manufacturer": "Hello Kitty Golf",
          "modelNumber": "GLOVE-HKG.M",
          "size": "20cm",
          "websiteDisplayGroup": "sports_display_on_website"
        }
      ]
    },
    {
      "asin": "B002W7RDMM",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "HELLO KITTY KT2054 Projection Clock Radio (Discontinued by Manufacturer)",
          "manufacturer": "HELLO KITTY",
          "modelNumber": "KT2054",
          "packageQuantity": 1,
          "partNumber": "KT2054",
          "websiteDisplayGroup": "ce_display_on_website"
        }
      ]
    },
    {
      "asin": "B00FFECUDQ",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "Hello Kitty Coffee Maker",
          "manufacturer": "Sakar Intl",
          "modelNumber": "APP-36209",
          "packageQuantity": 1,
          "style": "Coffee Maker",
          "websiteDisplayGroup": "kitchen_display_on_website"
        }
      ]
    },
    {
      "asin": "1534418717",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "Hello Robots! (A Hello Book)",
          "manufacturer": "Little Simon",
          "websiteDisplayGroup": "book_display_on_website"
        }
      ]
    },
    {
      "asin": "B001E0L3MO",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "HELLO KITTY 12009 Keychain Photo Frame",
          "manufacturer": "HELLO KITTY",
          "modelNumber": "12009",
          "packageQuantity": 1,
          "partNumber": "12009",
          "websiteDisplayGroup": "photo_display_on_website"
        }
      ]
    },
    {
      "asin": "B00021HBU4",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "Hello Kitty - 2-Slice Wide slot toaster with cool Touch Exterior",
          "modelNumber": "KT5211",
          "packageQuantity": 1,
          "partNumber": "KT5211",
          "websiteDisplayGroup": "speakers_display_on_website"
        }
      ]
    },
    {
      "asin": "B010VIOD0S",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "Hello Kitty School Bus Playset",
          "manufacturer": "Jada Toys - US",
          "modelNumber": "96981",
          "packageQuantity": 1,
          "partNumber": "96981",
          "websiteDisplayGroup": "toy_display_on_website"
        }
      ]
    },
    {
      "asin": "B074NHRVD6",
      "summaries": [
        {
          "marketplaceId": "ATVPDKIKX0DER",
          "brand": "Hello Kitty",
          "color": "Coral/Gold",
          "itemClassification": "BASE_PRODUCT",
          "itemName": "Hello Kitty 女童装饰短裙, 6, 珊瑚色",
          "manufacturer": "Hello Kitty",
          "modelNumber": "K3088751AM",
          "packageQuantity": 1,
          "partNumber": "K3088751AM-813-6",
          "size": "6",
          "style": "Hello Kitty Girls Embellished Tutu Dress",
          "websiteDisplayGroup": "apparel_display_on_website"
        }
      ]
    }
  ]
}

Paging in the response to a search for items in the Amazon catalog

When a call to the searchCatalogItems operation produces a response that exceeds the pageSize, pagination occurs. This means the response is divided into individual pages, where each page is returned in successive calls. 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.

You get the first page of results when you call the searchCatalogItems operation and provide no page token. You then iterate through the rest of the pages using the nextToken page token provided in successive responses.

Page tokens are special values that are decoded to determine which page is requested and how many pages are before or after.

If the next or previous page is not available, the corresponding page token attribute (nextToken or previousToken respectively) will not be present in the pagination object.

Examples:

When the response does not exceed the pageSize, there is no pagination, so there is no nextToken or previousToken:

"pagination": {
},

When the response exceeds the pageSize and pagination occurs:

For the first page, there is no previous page, so there is no previousToken:

"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"
},

📘

Note

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.

Updated 3 months ago