Manage Product Listings with the Selling Partner API
Manage your product listing lifecycle using SP-API.
This guide describes the lifecycle of listings on Amazon and the Selling Partner APIs that can be used to manage it.
Product listings lifecycle
The lifecycle of creating and managing listings on Amazon typically involves the following:
- Discovery
- Does Amazon already have the item I want to sell in its catalog?
- Where does my item fit within Amazon's catalog hierarchy?
- What is required to create items in the Amazon catalog?
- Am I eligible to list items in the Amazon catalog?
- Creation
- Have I met the data requirements to create a new item or list an existing item?
- Was my submission accepted?
- Maintenance
- What is the state of my listing? Is it buyable? Is it discoverable?
- Do I have any issues associated with my listing?
- Does my listing continue to meet Amazon data requirements?
Selling Partner APIs for Product Listings
The following Selling Partner APIs can help you manage your product listings:
- Product Type Definitions API: get the requirements for listing an item.
- Listings API: create and maintain listings.
- Catalog Items API: discover the contents of the catalog.
- Notifications API: receive updates about listings.
These APIs provide the following core capabilities for listing creation and management:
- Querying data from the Amazon catalog (ASINs).
- Querying and traversing the Amazon catalog hierarchy (classifications, browse nodes).
- Retrieving schemas describing Amazon data requirements by product type.
- Retrieving listings eligibility details by ASIN or product type.
- Creating, querying, updating, and deleting listings (SKUs).
In addition, these APIs provide programmatic notifications that enable event-driven workflows for third-party developers and sellers.
Product Type Definitions API
The Selling Partner API for Product Type Definitions provides programmatic access to attribute and data requirements for product types in the Amazon catalog. With this API, you request requirements for a product type in a given marketplace and receive responses including a JSON schema that describes all requirements, attributes, and the conditionality of the requirements. You can use this JSON schema to either validate the payload you already have or map it to your ERPs (Enterprise Resource Planning).
The following example uses the getDefinitionsProductType
operation to request the LUGGAGE
product type in the NA marketplace in American English:
GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/LUGGAGE
?marketplaceIds=ATVPDKIKX0DER
&locale=en_US
The following example shows a response to the preceding request and provides the ProductTypeDefinition
of the LUGGAGE
listing:
{
"metaSchema": {
"link": {
"resource": "https://...",
"verb": "GET"
},
"checksum": "QFQDmPwMARO7vwMEyLhOtw=="
},
"schema": {
"link": {
"resource": "https://...",
"verb": "GET"
},
"checksum": "TBr8ubaxXrUyay9hmxUXUw=="
},
"requirements": "LISTING",
"requirementsEnforced": "ENFORCED",
"propertyGroups": {
"offer": {
"title": "Offer",
"description": "Product Offer",
"propertyNames": [
"fulfillment_channel_availability",
"purchasable_offer",
"condition_type",
"condition_note",
"list_price",
"product_tax_code",
"merchant_release_date",
"merchant_shipping_group",
"max_order_quantity",
"gift_options",
"main_offer_image_locator",
"other_offer_image_locator_1",
"other_offer_image_locator_2",
"other_offer_image_locator_3",
"other_offer_image_locator_4",
"other_offer_image_locator_5"
]
},
"images": {
"title": "Images",
"description": "Physical imagess or URL's",
"propertyNames": [
"main_product_image_locator",
"other_product_image_locator_1",
"other_product_image_locator_2",
"other_product_image_locator_3",
"other_product_image_locator_4",
"other_product_image_locator_5",
"other_product_image_locator_6",
"other_product_image_locator_7",
"other_product_image_locator_8",
"swatch_product_image_locator"
]
},
"shipping": {
"title": "Shipping",
"description": "Information to determine shipping and storage of your product (e.g., package dimensions, weight, volume)",
"propertyNames": [
"item_dimensions",
"item_package_dimensions",
"item_package_weight"
]
},
"variations": {
"title": "Variations",
"description": "Variations that product will use",
"propertyNames": [
"parentage_level",
"child_parent_sku_relationship",
"variation_theme"
]
},
"safety_and_compliance": {
"title": "Safety & Compliance",
"description": "Information to indicate product compliance, hazardous materials, and legal and safety warnings (e.g., lithium batteries, choking hazards, Consumer Product Safety Information Act (CPSIA))",
"propertyNames": [
"country_of_origin",
"warranty_description",
"batteries_required",
"batteries_included",
"battery",
"num_batteries",
"number_of_lithium_metal_cells",
"number_of_lithium_ion_cells",
"lithium_battery",
"supplier_declared_dg_hz_regulation",
"hazmat",
"safety_data_sheet_url",
"item_weight",
"ghs",
"supplier_declared_material_regulation",
"california_proposition_65",
"pesticide_marking"
]
},
"product_identity": {
"title": "Product Identity",
"description": "Information to uniquely identify your product (e.g., UPC, EAN, GTIN, Product Type, Brand)",
"propertyNames": [
"item_name",
"brand",
"supplier_declared_has_product_identifier_exemption",
"externally_assigned_product_identifier",
"merchant_suggested_asin",
"item_type_keyword",
"item_type_name",
"model_number",
"manufacturer"
]
},
"product_details": {
"title": "Product Details",
"description": "Information and characteristics to describe the product to support search, browse and detail page content (e.g., bullets, product features, model, style name)",
"propertyNames": [
"product_description",
"bullet_point",
"special_feature",
"style",
"department",
"target_gender",
"age_range_description",
"material",
"outer",
"fabric_type",
"lining_description",
"number_of_items",
"number_of_wheels",
"wheel",
"model_name",
"color",
"size",
"size_map",
"part_number",
"compliance_media"
]
}
},
"locale": "en_US",
"marketplaceIds": [
"ATVPDKIKX0DER"
],
"productType": "LUGGAGE",
"productTypeVersion": {
"version": "U8L4z4Ud95N16tZlR7rsmbQ==",
"latest": true,
"releaseCandidate": false
}
}
Feeds JSON Schemas
Using Feeds JSON Schemas you can update individual listings in bulk. These schemas work with the Product Type Definitions API and allow integrators to create, edit, and delete Amazon listings (SKUs) with the same data format used by the Listings Items API. Listings data is interoperable between the Listings Items API and the JSON_LISTINGS_FEED
feed type, allowing selling partners to use the mechanism or combination that works best for their listings workflows.
Listings Items API
The Selling Partner API for Listings Items provides programmatic access to selling partner listings on Amazon. With this API, you can can create and edit your listings on an individual basis. It has four operations:
-
putListingsItem
allows you to create a given SKU and update attributes like price, inventory, or both. -
patchListingsItem
allows you to update the the attributes of a given SKU. -
deleteListingsItem
allows you to delete a given SKU. -
getListingsItem
returns information about a a given SKU.
The JSON listings feed is a new feed type. The JSON listings feed is the similar to the Listings API in that it allows you to update in bulk, use the Product Type Definitions API to get the schema, and put together a payload. This payload can either be submitted to the Listing Items API, or in bulk to the JSON listings feed.
The following example uses the getListingsItem
operation to request an Item
from a seller with a sellerId
of AXXXXXXXXXXXX
in the NA marketplace in American English. It requests summaries
, attributes
, issues
, offers
, and fulfillmentAvailability
to be in the Item
in the response:
GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/example-sku
?marketplaceIds=ATVPDKIKX0DER
&issueLocale=en_US
&includedData=summaries,attributes,issues,offers,fulfillmentAvailability
The response to this request is an Item
with summaries
, attributes
, issues
, offers
, and fulfillmentAvailability
:
{
"sku": "example-aku",
"summaries": [
{
"marketplaceId": "ATVPDKIKX0DER",
"asin": "XXXASINXXX",
"productType": "DRINKING_CUP",
"conditionType": "new_new",
"status": [
"BUYABLE",
"DISCOVERABLE"
],
"itemName": "6 Pack Coffee Mug Set, Farielyn-X 16 Ounce Ceramic Coffee Cups, Black Large Coffee mugs, Restaurant Coffee Cups for Coffee, Tea, Cappuccino, Cocoa, Cereal, Matte Black Outside and Colorful Inside",
"createdDate": "2021-07-14T19:57:02.327Z",
"lastUpdatedDate": "2021-07-14T19:57:10.637Z",
"mainImage":
{
"link": "https://m.media-amazon.com/images/I/41epVg7mZoS.jpg",
"height": 500,
"width": 500
}
}
],
"attributes":
{
"condition_type": [
{
"value": "new_new",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"merchant_shipping_group": [
{
"value": "legacy-template-id",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"merchant_suggested_asin": [
{
"value": "XXXASINXXX",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"purchasable_offer": [
{
"currency": "USD",
"start_at":
{
"value": "2021-07-14T19:56:57.717Z"
},
"our_price": [
{
"schedule": [
{
"value_with_tax": 30.0
}
]
}
],
"marketplace_id": "ATVPDKIKX0DER"
}
],
"fulfillment_availability": [
{
"fulfillment_channel_code": "DEFAULT",
"quantity": 1,
"marketplace_id": "ATVPDKIKX0DER"
}
],
"main_product_image_locator": [
{
"media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxx1.jpg",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"other_product_image_locator_1": [
{
"media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx2.jpg",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"other_product_image_locator_2": [
{
"media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx3.jpg",
"marketplace_id": "ATVPDKIKX0DER"
}
]
},
"issues": [
{
"message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): item_weight, theme, item_dimensions, item_diameter",
"severity": "WARNING",
"attributeName": "item_diameter",
"attributeNames": [
"item_diameter",
"item_dimensions",
"item_weight",
"theme"
]
},
{
"message": "Attributes tagged as customer_returns are incomplete. Provide values for the following attribute(s): color, item_dimensions, item_weight",
"severity": "WARNING",
"attributeName": "color",
"attributeNames": [
"color",
"item_dimensions",
"item_weight"
]
}
],
"offers": [
{
"marketplaceId": "ATVPDKIKX0DER",
"offerType": "B2C",
"price":
{
"currency": "USD",
"amount": "30.0"
}
}
],
"fulfillmentAvailability": [
{
"fulfillmentChannelCode": "DEFAULT",
"quantity": 1
}
]
}
Catalog Items API
The Selling Partner API for Catalog Items provides programmatic access to information about items in the Amazon catalog. In other words, you can search Amazon's catalog for products, match your products to the existing product listings on Amazon, and then make sourcing and pricing decisions for listing those products. The Catalog Items API is similar to the MWS Products API section's GetMatchingProduct
operation.
The following example uses the getCatalogItem
operation to request an item with ASIN XXXXXXXXXX
in the NA marketplace. It requests a response with an Item
that contains attributes
, identifiers
, images
, productTypes
, salesRanks
, summaries
, variations
, and vendorDetails
:
GET https://sellingpartnerapi-na.amazon.com/catalog/2022-04-01/items/XXXXXXXXXX
?marketplaceIds=ATVPDKIKX0DER
&includedData=attributes,identifiers,images,productTypes,salesRanks,summaries,variations,vendorDetails
The response to this request contains an Item
with all the requested information:
{
"asin": "XXXXXXXXXX",
"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": "50400150",
"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 Electronics",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"control_method": [
{
"value": "voice",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"item_package_dimensions": [
{
"length": {
"unit": "centimeters",
"value": ###
},
"width": {
"unit": "centimeters",
"value": ###
},
"height": {
"unit": "centimeters",
"value": ###
},
"marketplace_id": "ATVPDKIKX0DER"
}
],
"image_aspect_ratio": [
{
"language_tag": "en_US",
"value": "##:#",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"part_number": [
{
"value": "XXX",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"includes_remote": [
{
"value": true,
"marketplace_id": "ATVPDKIKX0DER"
}
],
"item_type_name": [
{
"language_tag": "en_US",
"value": "TV",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"battery": [
{
"cell_composition": [
{
"value": "XXX"
}
],
"marketplace_id": "ATVPDKIKX0DER"
}
],
"manufacturer": [
{
"language_tag": "en_US",
"value": "XXX",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"number_of_boxes": [
{
"value": #,
"marketplace_id": "ATVPDKIKX0DER"
}
],
"total_usb_ports": [
{
"value": #,
"marketplace_id": "ATVPDKIKX0DER"
}
],
"model_number": [
{
"value": "XXX",
"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": [
"xxx"
],
"marketplace_id": "ATVPDKIKX0DER"
}
],
"display": [
{
"resolution_maximum": [
{
"unit": "pixels",
"language_tag": "en_US",
"value": "XX x XX"
}
],
"size": [
{
"unit": "inches",
"value":##
}
],
"type": [
{
"language_tag": "en_US",
"value": "****"
}
],
"marketplace_id": "ATVPDKIKX0DER"
}
],
"item_name": [
{
"language_tag": "en_US",
"value": "XXX",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"list_price": [
{
"currency": "USD",
"value": $$$,
"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": "XXX",
"marketplace_id": "ATVPDKIKX0DER"
},
{
"language_tag": "en_US",
"value": "XXX",
"marketplace_id": "ATVPDKIKX0DER"
},
{
"language_tag": "en_US",
"value": "XXX",
"marketplace_id": "ATVPDKIKX0DER"
},
{
"language_tag": "en_US",
"value": "XXX",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"specification_met": [
{
"language_tag": "en_US",
"value": "",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"cpsia_cautionary_statement": [
{
"value": "XXX",
"marketplace_id": "ATVPDKIKX0DER"
}
],
"item_type_keyword": [
{
"value": "XXX",
"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"
}
],
"item_package_weight": [
{
"unit": "kilograms",
"value": 62.142,
"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"
}
],
"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"
}
],
"refresh_rate": [
{
"unit": "hertz",
"language_tag": "en_US",
"value": "120",
"marketplace_id": "ATVPDKIKX0DER"
}
]
},
"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/51DZzp3w3vL.jpg",
"height": 333,
"width": 500
}
]
}
],
"productTypes": [
{
"marketplaceId": "ATVPDKIKX0DER",
"productType": "TELEVISION"
}
],
"ranks": [
{
"marketplaceId": "ATVPDKIKX0DER",
"ranks": [
{
"title": "Electronics",
"link": "http://www.amazon.com/gp/bestsellers/electronics",
"value": 61667
},
{
"title": "QLED TVs",
"link": "http://www.amazon.com/gp/bestsellers/electronics/21489946011",
"value": 84
}
]
}
],
"summaries": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandName": "Samsung Electronics",
"colorName": "Black",
"itemName": "Samsung QN82Q60RAFXZA Flat 82-Inch QLED 4K Q60 Series (2019) Ultra HD Smart TV with HDR and Alexa Compatibility",
"manufacturer": "Samsung",
"modelNumber": "QN82Q60RAFXZA",
"sizeName": "82-Inch",
"styleName": "TV only"
}
],
"variations": [
{
"marketplaceId": "ATVPDKIKX0DER",
"asins": [
"B08J7TQ9FL"
],
"variationType": "CHILD"
}
],
"vendorDetails": [
{
"marketplaceId": "ATVPDKIKX0DER",
"brandCode": "SAMF9",
"categoryCode": "50400100",
"manufacturerCode": "SAMF9",
"manufacturerCodeParent": "SAMF9",
"productGroup": "Home Entertainment",
"replenishmentCategory": "OBSOLETE",
"subcategoryCode": "50400150"
}
]
}
Notifications API
The Selling Partner API for Notifications lets you subscribe to various notifications that are relevant to a selling partner's business. The following notifications provide useful information for listing items:
ITEM_PRODUCT_TYPE_CHANGE
: Sent when there is a change to the product type of any item that the selling partner has a brand relationship with.LISTINGS_ITEM_STATUS_CHANGE
: Sent when the status of a listings item changes for a selling partner. This notification is published when a listings item is created, deleted, or its buyability changes.LISTINGS_ITEM_ISSUES_CHANGE
: Sent when there is a change to the issues associated with a listings item that the selling partner owns. Issues point out that the listings item has problems which cause listings to go inactive, search suppression, or other quality problems.PRODUCT_TYPE_DEFINITIONS_CHANGE
: Sent when there is a new product type or product type version.
For more information on subscribing to notifications, refer to the Notifications Use Case Guide and the createSubscription
operation.
Updated 1 day ago