Listings Items API FAQ

Items will show as restricted if you don’t have access to the product type. If you have access issues, reach out to your vendor manager or through Contact Us, making sure to specify that your issue is an API inquiry.

Price increases to existing items are not possible via API. Significant price decreases also need to be verified. In this case, contact your vendor manager or open a Contact Us case. Then, upload your cost changes through Items > Edit Item Costs.

In some edge cases the schema might have changed and the original values that a vendor submitted are no longer valid. If this is the case, ask the vendor to raise a case with the Amazon Support team.

A+ premium content is not supported.

The APIs provide an alternative method of sending catalog data to Amazon. Downstream process and rules governing catalog data are the same regardless of submission method. In some cases, especially where we already have a listing for a product, the information submitted by a vendor might not have priority.

The summary view is a summary of the ASIN you are creating a listing against. If the summary view is not populated it is because the submission failed and did not match an ASIN. Make sure to check the schema and format for your product type and try again. If the issue persists, open a Developer Support case.

Your listing might have experienced an issue after submission (an asynchronous issue). To view such issues, use the getListingsItem operation.

If you receive a “Doesn’t match your product categories” message, the ASIN is set up in a product category the vendor does not have access to. Submit a Contact Us case via Vendor Central noting the message, ASIN(s), and correct product type. Open a case with Developer Support if you require technical support or where indicated in the troubleshooting guide.

If you receive a “Not Supported – the following products cannot be added” message, submit a Contact Us case via Vendor Central noting the issue message and impacted ASINs / external ID(s). Open a case with Developer Support if you require technical support or where indicated in the troubleshooting guide.

To identify the appropriate listing requirements, you must first select the correct product type. This will allow Amazon to provide all necessary listing requirements upfront. The following steps outline the process:

1. Use the searchDefinitionsProductTypes operation to get a list of applicable product types for your selling partners. If you have a product title, you can get a high-confidence recommendation for the product type by passing the itemName parameter. With the itemName parameter, you can combine the product title and description to get more granular product type suggestions. You can also use keywords to search through product types or pass an empty parameter to return the entire list of available product types. For additional information, refer to the Product Type Definitions API v2020-09-01 Use Case Guide.

2. After you know the product type, call the getDefinitionsProductType operation with the requirements parameter to retrieve the requirements to create a new listing.

Yes. The schema version always updates to the latest version of the Amazon product type definition.

There are multiple ways to identify changes between two schema versions:

• Call the getDefinitionsProductType operation and examine the checksum property in the response.
• Subscribe to the PRODUCT_TYPE_DEFINITIONS_CHANGE notification to receive real-time updates whenever new a product type version becomes available for a marketplace. If a new product type version triggered the notification, the notification payload provides the new product type version in the ProductTypeVersion property.
• Pay attention to the launch announcements Amazon provides every month (for example, https://developer-docs.amazon.com/sp-api/changelog/update-october-updates-to-listing-attribute-usage-and-enumeration-values). For more information, refer to Announcements.

Based on customer search and buying signals, Amazon reviews product attributes regularly and plans necessary updates for the last week of every month. Sometimes, Amazon makes some updates before the planned release to address customer feedback and resolve any defects or gaps. Most of the changes are minor and don't affect customer behavior. Before you update any attribute for your listing submission, use the Product Type Definitions API to get the latest JSON schema.

Use the $lifecycle attribute to find details about deprecated content and actions to take. Deprecated content is content that is still technically valid but will be removed in the future. For example, the enumDeprecated element of the $lifecycle attribute lists deprecated enumeration values that you should work to replace with the latest values.

You can list items on Amazon in the following ways:

• You can use the Listings Items API v2021-08-01 to programmatically access selling partner listings on Amazon. Use this API to create, edit, delete, and retrieve details about Amazon listings (SKUs) for a selling partner. For example, you can edit product facts such as item titles, and sales terms such as prices.
• You can use the JSON_LISTINGS_FEED, which is a bulk feed format that is interchangeable with the Listings Items API v2021-08-01 operations. The feed enqueues your bulk submission and then invokes the Listings Items API v2021-08-01 on your behalf. After the operation completes, the feed processing report includes validation feedback from the Listings Items API v2021-08-01.

For more information, refer to the Building Listings Management Workflows Guide.

The Catalog Items API v2022-04-01 provides information at the ASIN level, which is reconciled from various listings against that item. The Listings Items API v2021-08-01 provides information about the specific listing submitted by a selling partner.

Yes. The Catalog Items API v2022-04-01 returns data associated with an ASIN. An ASIN represents the same physical item in every marketplace, with few exceptions. However, the data for each ASIN differs by marketplace because countries have different data requirements specific to that marketplace.

Additionally, because most attributes are localized text, the text can differ depending on the marketplace or locale, even when the text describes the same product. Use the marketplaceIds filter in the Product Type Definitions API v2020-09-01 operations to get the marketplace-specific requirements to create or update products.

Yes. If you don't have a product identifier, you can create a product with a GTIN exemption. For exemption, you must submit a manual exemption request through your Seller Central account. For more information, refer to Seller Central. After you have received an approval, you can create a listings submission through the Listings Items API v2021-08-01. You must provide GENERIC as the brand name and set the supplier_declared_has_product_identifier_exemption attribute to true.

No. Amazon uses submission timestamps to ensure updates happen in the correct order.

When you upload a JSON_LISTINGS_FEED with product updates, Amazon records the feed submission time as the timestamp for all updates within the feed. If you then initiate an inventory update through the patchListingsItem operation, the system assigns the request submission time as the timestamp for that inventory update. In this scenario, the inventory update doesn't overwrite the product update because the timestamp of the inventory update is later than the timestamp of the product update.

Another example - you upload a JSON_LISTINGS_FEED and then initiate an inventory update through the patchListingsItem operation for the same SKU. If the patchListingsItem operation gets processed first, then it will override the data provided in the JSON_LISTINGS_FEED.

No. The JSON_LISTINGS_FEED and Listings Items API v2021-08-01 supports a single marketplace per feed.

Brand owners have the highest precedence to update data on the product details page on Amazon. If Amazon uses its own data on the product details page, brand owners can override it via a ticket to Seller Central support.

Before you submit a listing, verify that the attributes of the listing adhere to the JSON schema for the product type. For information about JSON schema validation utilities, refer to Amazon Product Type Definitions Meta-Schema (v1).
After you validate the JSON, you can preview errors before you create or update a listing by using VALIDATION_PREVIEW mode. This mode provides a test environment that checks the values that you provide in the payload for validation errors. VALIDATION_PREVIEW mode synchronously performs the same checks that are done on production submissions, but without persisting to your catalog.

Amazon performs multiple validations on listing submissions made by selling partners. Some of these validations are returned synchronously in response to the submissions. If you upload the listings data with the Listings Items API v2021-08-01 and the submission status is ACCEPTED, then the submission passed the synchronous validations. Amazon sends the submission downstream to create or update the SKU. There are a number of downstream processes that are then performed to create or update an item in the Amazon catalog. Any of these downstream processes can generate issues which are returned asynchronously. For example, if a listing submission contains data which conflicts with another item in the Amazon catalog. To create or update items successfully in the Amazon catalog, you must handle reported issues synchronously and asynchronously. For more information about listing issues, refer to Handling listings item issues and Listings Items API Issues Troubleshooting.

Amazon sends a LISTINGS_ITEM_STATUS_CHANGE notification when the status of a listing item changes. A notification gets published when the buyability changes for a listing item, or upon the creation or deletion of a listing item. To receive a notification when a listing gets created, subscribe to the LISTINGS_ITEM_STATUS_CHANGE notification. The ListingsItemStatus attribute returned in the payload contains the current status associated with the affected listings item. If there is no value, the status state is not applicable to the listings item. For example, if DISCOVERABLE is not present, Amazon retail cannot search for the listings item.

There can be a delay because the Amazon backend updates every 15 minutes. As a result, every update might be delayed by 0-15 minutes depending on when the update occurred in that window.
For example, a 15-20 minute delay for the LISTINGS_ITEM_ISSUES_CHANGE and LISTINGS_ITEM_STATUS_CHANGE notifications is normal. Our data sources can be up to 15 minutes behind because the data sources rely on many upstream processes to send updates for notifications.

In contrast, the getListingItem operation directly queries the current state, which is why the results are available faster (within 1-5 minutes). To minimize throttling errors, Amazon recommends that you use push notifications to receive real-time updates for status changes and issues with listings.

Throughout the process phase of a listing submission, Amazon evaluates the listing. If the listing deviates from the selected product type, the listing's product type will switch to the Amazon recommended product type. This results in attributes from the new product type to show up as missing. We convey information about a changed product type through a warning on the listing.

Amazon recommends that you use the searchDefinitionsProductTypes operation to retrieve a list of all the applicable product types. To retrieve a high-confidence recommendation for the correct product type with this operation, use the itemName parameter.

With the JSON_LISTINGS_FEED, you can send up to 10,000 SKUs in a single request every 5 minutes. To prevent throttling issues, instead of sending small feeds, send one large feed. Uploading multiple small feeds every few seconds is inefficient and can result in a backlog. This can block other feeds from processing and force you to cancel some of the previously submitted feeds. Instead of sending the same data, only send updated information to reduce the number of calls. For information about how to optimize your feed submissions, refer to Feeds API Best Practices.

The image attributes provided by the Listings Items API v2021-08-01 operations map images to ASINs at a global level where the ASIN exists, even if you specify the marketplace_id selector. This behavior is consistent with other experiences, such as Add a Product within Seller Central.