Building Listings Management Workflows Guide

This guide summarizes the steps you can take to build best-in-class listings creation and management workflows by integrating with the Selling Partner API. By following the recommended steps, you can minimize the friction that selling partners experience while creating and managing their listings on Amazon.

📘

Note

As a supplement to this guide, the SellingPartnerAPIListingSampleApplication instructions on GitHub provide an optional solution that demonstrates how to use the APIs in this guide to construct common listings management workflows using a simple UI with AWS services.

API versions

This guide references operations in the following Selling Partner API sections. For more detailed information about the individual API operations listed, follow the referenced links.

Terminology

• Catalog item: Represents an item in Amazon's catalog and is uniquely identified by an Amazon-defined ASIN (Amazon Standard Identification Number). Data from one or more selling partner listings items are reconciled into a single item in Amazon's catalog and represents the product facts for an item sold on Amazon.

• Listings item: Represents an item (a.k.a. a listing) in a selling partner catalog that is uniquely identified by a selling partner-provided SKU and represents the product facts and sales terms for an item sold on or fulfilled by Amazon.

• JSON Schema: JSON is the serialization format used by the APIs, notifications, and feed formats described in this guide. JSON Schema is a vocabulary for annotating, describing, and validating JSON content and is used by the Product Type Definitions API to describe the data model for Catalog Items and Listings Items. Refer to What is JSON Schema for more details about JSON Schema.

• JSON_LISTINGS_FEED: The JSON_LISTINGS_FEED is a bulk feed format contractually compatible with the APIs outlined in this guide and is interchangeable with the individual Listings Items API operations. Refer to Creating and updating listings items in bulk for more information.

• Variation family: A variation family is a collection of similar items that vary by color, size, or other attributes used to provide a single detail page experience for buyers on Amazon. For example, a clothing article can come in multiple colors, multiple sizes, and multiple styles. Each unique combination of color, size, and style is represented by a separate item in the variation family.

Listing items on Amazon

Listing items on Amazon can take multiple forms, depending on your specific use-case. The steps described here provide examples of how the API and notification building blocks can be composed for commonly used listings workflows.

📘

Product types

Amazon is in the process of migrating product types to enable their support in the Listings Items API and the Product Type Definitions API. For product types not yet launched for these APIs, you can create new offer-only listings items, edit sales terms for listings items, or delete listings items. However, you cannot create new listings items with product facts until the appropriate product type is launched in these APIs. You can use the searchDefinitionsProductTypes operation and the PRODUCT_TYPE_DEFINITIONS_CHANGE notification to keep up-to-date with the available product types. Refer to the Notifications API v1 Use Case Guide for information about setting up a destination and creating subscriptions.

Subscribe to listings notifications

Each of the workflows described here can result in asynchronous status changes or issues on your listings items. By subscribing to and monitoring the LISTINGS_ITEM_STATUS_CHANGE and LISTINGS_ITEM_ISSUES_CHANGE notifications, you are empowered to build event-driven workflows that react in realtime as these changes occur. Refer to the Notifications API v1 Use Case Guide for information about setting up a destination and creating subscriptions.

List an item that does not already exist in the Amazon catalog

The following diagram provides an overview of the workflow steps to create a listing for an item that does not already exist in the Amazon catalog.

Follow these steps to identify if an item exists in the Amazon catalog, retrieve the data requirements for listing a new item, submit a new item, and receive notifications generated as a result.

1. Call the searchCatalogItems operation to search for existing items in the Amazon catalog by product identifiers (for example, UPC, EAN) or keywords. If an exact match is found, use the List an offer for an item that already exists in the Amazon catalog steps to create an offer-only listings item. If an exact match is not found, continue to the next step.

2. Call the searchDefinitionsProductTypes operation to retrieve the applicable product type for your item. If the product title is available, you can retrieve a high-confidence recommendation for the correct product title by passing itemName, or you can usekeywords to search through product types. You can pass an empty parameter to return the entire list of available product types. Refer to the Product Type Definitions API v2020-09-01 Use Case Guide for additional details.

3. Call the getDefinitionsProductType operation to return the JSON Schema describing the attributes and constraints for the product type.

📘

Listing requirements

Listing items on Amazon can be done with or without providing offer details (sales terms) at the time of creation. This enables you to create items that are purchasable or procurable in one submission or to create inactive items with sales terms provided later. To list an item with both product facts and sales terms, use the LISTING as the value for the requirements parameter to retrieve a JSON Schema with both product and offer attributes. To list an item with product facts only, use the LISTING_PRODUCT_ONLY as the value for the requirements parameter to retrieve a JSON Schema with product attributes only.

4. Prepare the listing submission with attributes adhering to the JSON Schema for the product type.

5. Check that the listing data meets requirements prior to submission by using JSON Schema validation utilities. Refer to Amazon Product Type Definition Meta-Schema (v1) for more details on validating data with the product type JSON Schemas. You must ensure that the required attributes are provided, all values are valid, any conditional rules are accounted for, and all schema requirements are met.

6. Call the putListingsItem operation to submit the listings item.

7. Inspect the response to identify if the submission status was ACCEPTED or INVALID. If accepted, initial validations have passed and the data has been submitted for further processing with the Amazon catalog. If invalid, one or more validation issues prevented acceptance; refer to Handling listings item issues for more information. Correct the validation issues and resubmit.

8. Wait for the LISTINGS_ITEM_STATUS_CHANGE or LISTINGS_ITEM_ISSUES_CHANGE asynchronous notifications sent when the new item has been created or processing issues have occurred. Call the getListingsItem operation to inspect the listings item issues, if applicable.

   You must subscribe to the notifications mentioned to receive them. Refer to Subscribe to listings notifications for more information.

List an offer for an item that already exists in the Amazon catalog

The List an item that does not already exist in the Amazon catalog steps described listing an item that does not already exist in the Amazon catalog. For items that already exist in the Amazon catalog, sellers can choose to list only the necessary details to match the existing item along with the applicable sales terms.

📘

Offer-only listings

Note that offer-only listings are not supported for vendors at this time. For all items, vendors must provide product facts and sales terms as described in the List an item that does not already exist in the Amazon catalog steps.

The following diagram provides an overview of the workflow steps to create a listing for an item that already exists in the Amazon catalog.

1. Call the searchCatalogItems operation to search for existing items in the Amazon catalog by product identifiers (for example, UPC, EAN) or keywords. If an exact match is found, continue to the next step. If an exact match is not found, the item needs to be created as described in the List an item that does not already exist in the Amazon catalog steps.

2. Call the getListingsRestrictions operation with the ASIN identifier to retrieve any eligibility requirements that must be met before listing an item in the applicable condition.

3. Call the getDefinitionsProductType operation to return the JSON Schema describing the attributes and constraints using the PRODUCT product type and LISTING_OFFER_ONLY as the value for the requirements parameter.

📘

Amazon product types

Amazon product types are hierarchal, with the PRODUCT product type as the root for all product types. Sales terms are defined on the root PRODUCT product type, which should be used when listing items with sales terms only.

4. Prepare the listing submission with attributes adhering to the JSON Schema for the PRODUCT product type using the ASIN or product identifier for the item found when searching the Amazon catalog.

5. Check that the listing data meets requirements prior to submission by using JSON Schema validation utilities. Refer to Amazon Product Type Definition Meta-Schema (v1) for more details on validating data with the product type JSON Schemas. You must ensure that the required attributes are provided, all values are valid, any conditional rules are accounted for, and all schema requirements are met.

6. Call the putListingsItem operation to submit the listings item.

7. Inspect the response to identify if the submission status was ACCEPTED or INVALID. If accepted, initial validations have passed and the data has been submitted for further processing with the Amazon catalog. If invalid, one or more validation issues prevented acceptance; refer to Handling listings item issues for more information. Correct the validation issues and resubmit.

8. Wait for the LISTINGS_ITEM_STATUS_CHANGE or LISTINGS_ITEM_ISSUES_CHANGE asynchronous notifications sent when the new item has been created or processing issues have occurred. Call the getListingsItem operation to inspect the listings item issues, if applicable.

   You must subscribe to the notifications mentioned to receive them. Refer to Subscribe to listings notifications for more information.

Previewing errors for a listings item

Validation preview provides a test environment that can be used to test listing workflows, including validation errors that prevent listing creation. Refer to the following tutorials for more information on how to preview errors for a listing prior to submission:

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

Updating a listings item

The following diagram provides an overview of the workflow steps to update a listings item.

Follow these steps to update the attributes for a listings item.

1. Identify the selling partner SKU that needs to be updated.

2. If you need to inspect the existing attributes, then call the getListingsItem operation using the identified SKU. Be sure to include attributes and issues in the list of values for the includedData parameter.

3. Call the getDefinitionsProductType operation to return the JSON Schema describing the attributes and constraints for the product type. Use LISTING or LISTING_PRODUCT_ONLY for the requirements parameter depending on the attributes that will be updated. Refer to Listing requirements for more information.

4. Prepare the listing submission with attributes adhering to the JSON Schema for the product type. Non-editable values ("editable": false) cannot be modified from their existing values.

5. Check that the listing data meets requirements prior to submission by using JSON Schema validation utilities. Refer to Amazon Product Type Definition Meta-Schema (v1) for more details on validating data with the product type JSON Schemas. You must ensure that the required attributes are provided, all values are valid, any conditional rules are accounted for, and all schema requirements are met.

6. Call the patchListingsItem or putListingsItem operation depending on whether you want to do a partial or full update.

   Selling partners can update a listing by providing the individual attribute(s) to update using the patchListingsItem operation (partial update) or by providing all listings item attribute(s) using the putListingsItem operation (full update).

   For sellers, using the putListingsItem operation will replace previously submitted product fact attributes and merge previously submitted sales term attributes. For example, omitting an optional product fact will result in its removal. Conversely, however, omitting a purchasable offer price value will not result in its removal. Sellers can use the patchListingsItem to add, replace, or remove one or more attribute values.

   For vendors, using the putListingsItem operation will merge the provided attributes with previously submitted attributes. Omitting an optional attribute will not result in its removal. Vendors can use the patchListingsItem to add or replace one or more attribute values. However, deleting individual attribute values is not supported for vendors at this time.

📘

Partial vs. full updates

Use the patchListingsItem operation to make partial updates to a product listing. The advantage to using the patchListingsItem operation is that you only need to include the attributes that are changing (and are editable). However, it is also possible to add, replace, or delete attributes using the putListingsItem operation. If you choose to use the putListingsItem operation, you must prepopulate the request payload with the output of the getListingsItem operation for all identifying attributes (including uneditable attributes) to avoid submission errors. This essentially means replacing the attribute data for the entire listing. For that reason, using the putListingsItem operation is best suited to a full update.

7. Inspect the response to identify if the submission status was ACCEPTED or INVALID. If accepted, initial validations have passed and the data has been submitted for further processing with the Amazon catalog. If invalid, one or more validation issues prevented acceptance; refer to Handling listings item issues for more information. Correct the validation issues and resubmit.

8. Wait for the LISTINGS_ITEM_STATUS_CHANGE or LISTINGS_ITEM_ISSUES_CHANGE asynchronous notifications sent when the new item has been created or processing issues have occurred. Call the getListingsItem operation to inspect the listings item issues, if applicable.

   You must subscribe to the notifications mentioned to receive them. Refer to Subscribe to listings notifications for more information.

Deleting a listings item

Refer to Tutorial: Delete a listing in the Listings Item Use Case Guide for more information on how to delete a listing.

Creating and updating listings items in bulk

The workflows listed in this document for creating, updating, and deleting listings items operate on individual items one at a time. For high-volume workflows where bulk submission mechanisms are preferred, you can also use the JSON_LISTINGS_FEED feed type with the Feeds API.

The following diagram provides an overview of the workflow steps to create and update a listings items in bulk.

The JSON_LISTINGS_FEED feed type is contractually compatible with the Listings Items API and attributes in feed messages follow the same product type definition schemas provided by the getDefinitionsProductType operation. These feed submissions will enqueue your bulk submission and then invoke the Listings Items API on your behalf. When complete, the feed processing report will include any validation feedback provided by the Listings Items API.

Refer to Workflow for submitting a feed for details on how to submit a feed, and refer to the JSON_LISTINGS_FEED Schema for the schema of the feed type.

Should I submit in bulk using the JSON_LISTINGS_FEED or individually with the Listings Items API?

📘

Improve the performance of your submissions

Whether you are submitting data in bulk with the JSON_LISTINGS_FEED, individually with the Listings Items API, or a combination of both, your overall processing times are impacted by the volume of data that you submit. Repeated submission of duplicate data increases your processing backlogs unnecessarily and results in longer processing times, such as resubmitting all listings for a seller in a feed submission when only one item actually changed. By submitting data only for items that have material changes, you will most efficiently use the capacity available and reduce processing delays.

You can use the same data when submitting individually to the Listings Items API or in bulk with the JSON_LISTINGS_FEED. Whether you use the individual Listings Items API operations, submit in bulk with the JSON_LISTINGS_FEED, or use a combination of both is up-to you, your use-case, and your preferences. You might choose to use the JSON_LISTINGS_FEED to perform an initial load of your data into Amazon and transition to using the Listings Items APIs to maintain that data over time. You might choose to exclusively use the JSON_LISTINGS_FEED to perform daily synchronizations of changes to Amazon. Or you might choose to exclusively use the Listings Items API to receive synchronous validation feedback as you submit your data one item at a time.

The following table compares the Listings Items API and JSON_LISTINGS_FEED features to aide you in deciding which to use in your workflows:

Handling listings item issues

Issues can occur on listings items during submission or during asynchronous processing after acceptance. These issues are made available via the following mechanisms:

1. For issues that occur during synchronous submissions to the Listings Items API, the responses contain the list of issues that prevented acceptance of the submission. For the list of issues provided, take corrective actions and resubmit.

2. For issues that occur during asynchronous ingestion of JSON_LISTINGS_FEED submissions to the Listings Items APIs, the feed processing report contains the list of issues that prevented acceptance of the submissions. For the list of issues provided, take corrective actions and resubmit.

3. For issues that occur after acceptance of submissions to the Listings Items API or JSON_LISTINGS_FEED, the getListingsItem operation provides the list of issues when the includedData request parameter includes issues. Additionally, if subscribed to the LISTINGS_ITEM_ISSUES_CHANGE notification, a push notification will be sent in near realtime as issues are recorded. This empowers you to build event-driven response handling to retrieve more details from the getListingsItem operation when issues occur instead of repeatedly polling the operation.

Submitting images for listings items

Image related attributes are included in the product schemas returned by the getDefinitionsProductType operation (for example, main_offer_image_locator, other_offer_image_locator_1).

A main product image and up to nine secondary images can be uploaded using the Listings Items API by calling the putListingsItem or patchListingsItem operations and providing the image URLs.

Images associated with an ASIN or SKU can be retrieved using the getCatalogItem and getListingsItem operations respectively.

For more information, refer to Submitting images and other media attributes.

Configuring related listings items (variations, package hierarchies)

Listings items can be related to one another to create variation families or package hierarchies. The product type definition schemas provided by the getDefinitionsProductType operation describe the applicable attributes to define relationships, such as parentage_level and variation_theme.

Configuring variation families

A variation family represents a collection of items for one product that is sold in multiple varieties. For example, a clothing article can come in multiple sizes and colors. Each unique size and color combination is represented by a separate listings item and grouped together by a parent listings item to provide a single detail page experience. Follow these steps to configure a variation family for supported product types:

1. Follow the List an item that does not already exist in the Amazon catalog steps to create the parent listings item with the parentage_level value set to parent.

2. For each unique combination of variation family attributes, follow the List an item that does not already exist in the Amazon catalog steps to create the child listings items with the parentage_level value set to child and referencing the SKU identifier of the parent listings item.

📘

Support for configuring variation families

Configuring variation families with the Listings Items API is not supported for vendors at this time.

Configuring package hierarchies

A package hierarchy represents a collection of items for one product that is sold as individual units, in cases, and in case packs (that is, pallets). For example, a consumable beverage can be sold as an individual bottle, a case of six bottles, or a pallet containing 12 cases. When you create package hierarchies, consider the following:

• Follow the List an item that does not already exist in the Amazon catalog steps to create the item representing the individual sellable unit, case (innerpack) containing the individual unit and referencing the SKU identifier of the individual unit, or pallet (casepack) containing the case and referencing the SKU identifier of the case, with the package hierarchy attributes provided.
• Item package dimension attributes should be different across the package hierarchy. These attributes represent actual package dimensions when shipping to buyers.
• The recommended approach for the item_name value for the case (innerpack) and pallet (casepack) listings items is to append the package details to the item_name value used for the individual unit. For example, Pep 12oz Bottle, Pep 12oz Bottle (Case of six), and Pep 12oz Bottle (Pallet of 72).
• Each item in the package hierarchy must contain a unique external product identifier in order to be sold to buyers. For package hierarchies using a common external product identifier for each item, only one of the items will be available for sale to buyers.
• A package hierarchy relationship can be created by providing the package_level and package_contains attributes.

Setting a SKU as a unit example:

"package_level": [
  {
    "value": "unit"
  }
]

Setting a SKU as a case example:

When the SKU is a case or pallet, package_contains_sku points to the child SKU XXXXXXX and it includes quantity five of the child SKU.

"package_contains_sku": [
  {
    "quantity": 5,
    "sku": "XXXXXXX"
  }
],
"package_level": [
  {
    "value": "case"
  }
]

A package hierarchy relationship links units, case packs, and pallets of a product. This creates a connected listing, improving search visibility and detail page experience. For more information on Amazon Bulk Services, refer to Amazon Bulk Services: Overview on Seller Central.