Manage Listings Issues

The Listings Items API provides programmatic access to selling partner listings on Amazon. You can create, edit, delete, and retrieve details about Amazon listings (SKUs) for a selling partner. This includes product facts, such as item titles, and sales terms, such as price and inventory. When working with the Listings Items API, you may encounter issues during listing creation,
updates, or validation. This guide shows you how to identify, retrieve, and resolve these issues.

What are Listings Issues?

Within the listing experience, you can access issues during different parts of the process. When you submit data with the Listings Items API, Amazon performs validations that return responses synchronously or asynchronously.

Synchronous validation provides immediate feedback that prevents acceptance and further processing of the submission. If the submission passes the initial synchronous validations, the submission is accepted and is sent downstream to create or update the SKU. However, Accepted does not mean the process is complete. Multiple downstream processes create the item in the Amazon catalog, and any of these processes can generate issues that return asynchronously. During this processing, Amazon validates the submitted data against existing content and returns listings issues asynchronously.

It is crucial to manage effectively both synchronous and asynchronous issues to ensure smooth listing operations.

Issue types

There are two types of issues:

• Synchronous issues: Occur when the server rejects the initial submission and you can see the errors immediately. These cover input data validations, such as missing required attributes and invalid attributes.
• Asynchronous issues: Occur after a request passes initial validation but fail during downstream processing. These issues return as detailed messages with resolution guidance.

Access Listings issues

Listings issues are accessed through the following mechanisms:

• Direct API responses: Retrieve issues directly in the API responses for synchronous Listings Items API submissions that prevented acceptance.
• Direct API Requests: Use the getListingsItem (single SKU) or searchListingsItems (multiple SKUs) operations with the includedData=issues parameter to retrieve issue details about a single or multiple listings.
• JSON_LISTINGS_FEED processing reports: Access feed processing reports for the JSON_LISTINGS_FEED submissions through the Feeds API, which include both synchronous and asynchronous issues.
• Notifications: Subscribe to asynchronous LISTINGS_ITEM_ISSUES_CHANGE notifications to receive near real-time updates when the listings item issues change after making the submission.

Best practices to prevent Listings issues

The following sections help you understand how to prevent and handle listing errors effectively.

Pre-validate your Listings payload using the Product Type Definitions API

Listings data submitted to the Listings Items API must conform to the JSON Schema format provided by the Selling Partner API for Product Type Definitions. Use the Product Type Definitions API to retrieve the latest JSON schema for a product type and validate your payload against the meta-schema before submission. Verify required and conditionally required attributes, as dynamic conditions may change requirements based on other attribute values. Review the allOf property in the product type JSON schema to identify conditional requirements.

For more guidance, refer to the following resources:

• JSON schema support documentation.
• JSON schema tools for rendering user interfaces and validating listings data.
• Deep dive videos on using Product Type Definitions API to create and validate product JSON schemas.
• Selling Partner Listings sample application on GitHub demonstrates an end-to-end listings experience for managing common listings use cases. It features a dynamic UI implementation based on the product type JSON schema and provides a mini Seller Central experience where you can add, delete, update and test your listings. Follow the video to set up and install the application.

Preview listings errors using Validation Preview mode feature

❗

Important

This mode has lower rate limits and is intended for testing a small number of listings. It is not designed for production workflows.

The VALIDATION_PREVIEW feature in the Listings Items APIs provides a test environment to identify asynchronous errors that could prevent a listing from being created or updated, without persisting the data in production.

When you use the Validation Preview mode of the Listings Items API, the error codes in the issues array of the response is updated. The validation logic remains functionally equivalent, but error codes will change to reflect our enhanced validation system.

Action required

• Review your error handling logic: If your application parses or matches specific error codes from Validation Preview responses, update your code to handle both current and new error codes.
• Update error code mappings: Use the reference table below to map current error codes to their new equivalents in your application.
• Test with Validation Preview: We recommend testing your integration with the Validation Preview mode of the Listings Items API to observe the new error codes and ensure your application handles them correctly.
• Monitor your integration: Monitor your Validation Preview requests to identify any unexpected behavior.

The following table shows the mapping between current error codes and new error codes:

The following is an example of current Validation Preview response:

{
  "issues": [
    {
      "code": "90004145",
      "message": "The value provided for 'item_name' exceeds the maximum length of 200 characters.",
      "severity": "ERROR",
      "attributeName": "item_name"
    }
  ]
}

The following is an example of Validation Preview response change:

{
  "issues": [
    {
      "code": "90225",
      "message": "The value provided for 'item_name' exceeds the maximum length of 200 characters.",
      "severity": "ERROR",
      "attributeName": "item_name"
    }
  ]
}

Considerations

• Validation Preview mode only: These changes affect only the Validation Preview mode (mode=VALIDATION_PREVIEW) of the Listings Items API. Standard submission modes are not impacted.
• Validation logic unchanged: The underlying validation rules remain the same; only the error codes are changing.
• Message text may vary: While error codes are changing, the error messages may also be refined for clarity.
• Backward compatibility: We support both current and new error codes to ensure smooth operation.
• No action required for most integrations: If your application does not parse or match specific error codes, no changes are needed.

Refer to the following tutorials for more information on previewing errors for a listing before submission:

• Preview errors before creating or fully updating a listing
• Preview errors before partially updating a listing

Set up event-driven error handling

Subscribe to the LISTINGS_ITEM_ISSUES_CHANGE notifications to receive near real-time updates when issues on your Selling Partners' listings are created, fixed, or updated.

Each notification payload includes key listing identifiers such as SKU, along with related issue Severities, and EnforcementActions caused by issues. Implement event handlers to consume these notifications and call appropriate API operations (for example, getListingsItem or searchListingsItems) to retrieve detailed listings issues data based on the reported severities and actions.

This event-driven architecture eliminates the need for continuous polling, reduces direct API call volume, and enables faster detection of listing issues.

The following is an example of notification payload:

{
  "NotificationVersion":"1.0",  
  "NotificationType":"LISTINGS_ITEM_ISSUES_CHANGE",  
  "PayloadVersion":"2023-12-13",  
  "EventTime":"2021-02-03T18:59:30.194Z",
  "Payload":{
        "SellerId": "AXXXXXXXXXXXXX",
        "MarketplaceId": "ATVPDKIKX0DER",
        "Asin": "TEST",
        "Sku": "TEST",
        "Severities": [
            "ERROR",
            "WARNING"
    ],
    "EnforcementActions": [
      "SEARCH_SUPPRESSED",
      "LISTING_SUPPRESSED",
      "ATTRIBUTE_SUPPRESSED",
      "CATALOG_ITEM_REMOVED"
    ]
  },
  "NotificationMetadata":{  
        "ApplicationId":"amzn1.sellerapps.app.f1234566-aaec-55a6-b123-bcb752069ec5",  
        "SubscriptionId":"93b098e1-c42-2f45-93a1-78910a6a8369",  
        "PublishTime":"2021-02-03T18:59:30.194Z",  
        "NotificationId":"0e999936-da2c-4f9c-9fc2-02b67bae5f49"
    }
}

Use enhanced JSON Processing Report feature for Bulk Monitoring

By default, the JSON_LISTINGS_FEED processing report only includes a list of synchronous issues that prevented acceptance of the submissions. To retrieve a complete list of both synchronous and asynchronous processing issues, specify the issues parameter in the includedData property in the feed header when constructing a JSON feed payload.

The following is an example of a JSON feed with requested issues property set:

{
  "header": {
    "sellerId": "{{sellerId}}",
    "version": "2.0",
    "issueLocale": "en_US",
    "report": {
      "includedData": [
        "issues"
      ],
      "apiVersion": "2021-08-01"
    }
  },
  "messages": [
    {},{}
  ]
}

When you request issues in a JSON_LISTINGS_FEED submission, Amazon generates the processing report only after processing all feed items. You can use this feature to request other details (for example, summaries, attributes, etc.) about the listings item. Ensure that you pass only the information you need to optimize for the processing time. To request additional data in the enhanced processing reports, refer to the JSON_LISTINGS_FEED Processing report schema for the schema of the feed type and other available options.

Troubleshoot Listings Item Issues

The following diagram provides an overview of the workflow steps to handle listings item issues.

📘

Note

In most cases, implementing one best practice might not be enough. Combine multiple approaches (notifications, bulk operations, direct API calls) to effectively manage listings issues and reduce call volume.

Follow the steps to troubleshoot listings submission issues:

1. Identify the selling partner SKU with issues that need to be resolved.
2. If you need to inspect existing issues, call the getListingsItem operation with the identified SKU. Ensure that you include issues in the includedData parameter to retrieve a list of existing errors.
   • You can also use the searchListingsItems to retrieve information about multiple listings based on SKU, ASIN, or supported identifier. Refer to Search for listings items by product identifier or other listings parameters tutorial to learn more.
3. Review the issues object to inspect the associated listings issue. Verify the categories to understand the types of issues category and review the enforcements actions. Prioritize fixing issues that could impact the status of the selling partner listings. Address the critical issues relevant to your use case, then resubmit the corrected listing data. Refer to the Listings Items API reference documentation to see applicable values for issues, categories and enforcement actions.
4. For the JSON_LISTINGS_FEED, download and review the processing report after each upload. If you have requested an enhanced processing report in the feed submission, you will receive processing report only after Amazon validates and processes all the items present in the feed message.
5. For ongoing monitoring and automation, instead of repeatedly calling direct API operations, subscribe to asynchronous LISTINGS_ITEM_ISSUES_CHANGE and the LISTINGS_ITEM_STATUS_CHANGE notifications to receive listings issues reported after making the submission. Then inspect the information received in the notifications payload and call further APIs, if necessary.

For information on synchronous listings issues examples and preventative actions, refer to the Listings Items API Issues troubleshooting guide. To understand common asynchronous error messages, their definitions, and suggested solutions, refer to the Error code explanations in the Seller Central.

If you would like to share feedback on the error or report defects with errors, open a case with our developer support team.