Listings APIs FAQ
Frequently asked questions about Listings APIs.
Why are items showing as restricted / can’t be added?
Select to expand the answer.
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.
Can I edit my cost price via API?
Select to expand the answer.
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.
The original values submitted by the vendor are no longer accepted. How can we successfully submit?
Select to expand the answer.
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.
How do I update A+ premium Content?
Select to expand the answer.
A+ premium content is not supported.
Why are my edits not making it to the detail page even though they appear as successful?
Select to expand the answer.
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.
Why is there no summary information in my Listings Item Get API response?
Select to expand the answer.
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.
I submitted my listing without issues, but I cannot find it listed.
Select to expand the answer.
Your listing might have experienced an issue after submission (an asynchronous issue). To view such issues, use the getListingsItem
operation.
What does the “Does not match your product categories” issue message mean?
Select to expand the answer.
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.
What does the “Not Supported – the following products cannot be added” issue message mean?
Select to expand the answer.
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.
Product schemas
How do I determine the listing requirements to list a new product on Amazon?
Select to expand the answer.
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:
-
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 theitemName
parameter. With theitemName
parameter, you can combine the product title and description to get more granular product type suggestions. You can also usekeywords
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. -
After you know the product type, call the
getDefinitionsProductType
operation with therequirements
parameter to retrieve the requirements to create a new listing.
When the product type JSON schema changes, will the schema version update?
Select to expand the answer.
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 thechecksum
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 theProductTypeVersion
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.
How frequently do Amazon catalog requirements change?
Select to expand the answer.
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.
How do I use the $lifecycle
attribute in the Product type definition metadata in the workflow?
$lifecycle
attribute in the Product type definition metadata in the workflow?Select to expand the answer.
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.
Listings submissions
What are the different ways to programmatically list items on Amazon?
Select to expand the answer.
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.
What’s the difference between the Catalog Items API v2022-04-01 and the Listings Items API v2021-08-01?
Select to expand the answer.
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.
Can the data that the Catalog Items API v2022-04-01 returns differ by marketplace?
Select to expand the answer.
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.
Is it possible to create a product on Amazon without an ASIN or product identifier (UPC, GTIN, or EAN) with the Listings Items API v2021-08-01?
Select to expand the answer.
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
.
If I call patchListingsItem
after I call JSON_LISTINGS_FEED
, does the JSON feed update overwrite the patch call??
patchListingsItem
after I call JSON_LISTINGS_FEED
, does the JSON feed update overwrite the patch call??Select to expand the answer.
No. Amazon uses submission timestamps to ensure that updates happen in the correct order.
When you upload a JSON_LISTINGS_FEED
with inventory 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, if the patchListingsItem
operation gets processed first, then it overrides the data provided in the JSON_LISTINGS_FEED
.
Can I submit a JSON_LISTINGS_FEED
with multiple marketplaces?
JSON_LISTINGS_FEED
with multiple marketplaces?Select to expand the answer.
No. The JSON_LISTINGS_FEED
and Listings Items API v2021-08-01 supports a single marketplace per feed.
Who has the highest precedence to override the product details page information on Amazon?
Select to expand the answer.
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.
How can I validate my listings data before making a production call?
Select to expand the answer.
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.
When do I find out if there are issues with my listings?
Select to expand the answer.
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.
How can I confirm the creation of my product in the Amazon catalog?
Select to expand the answer.
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.
Why is there a noticeable delay between when changes to a listing item are reflected in the getListingItem
operation results versus when the LISTINGS_ITEM_ISSUES_CHANGE
and LISTINGS_ITEM_STATUS_CHANGE
notifications are received in the SQS queue?
getListingItem
operation results versus when the LISTINGS_ITEM_ISSUES_CHANGE
and LISTINGS_ITEM_STATUS_CHANGE
notifications are received in the SQS queue?Select to expand the answer.
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.
After I submit a product, why do I receive an error for missing attributes that are not part of the Product Type JSON schema?
Select to expand the answer.
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.
What should I do if I reach the rate limit with the JSON_LISTINGS_FEED
?
JSON_LISTINGS_FEED
?Select to expand the answer.
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.
Why was my image update applied globally?
Select to expand the answer.
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.
Updated 10 days ago