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.
|
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.
|
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.
|
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.
|
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 2 months ago