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 can't 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.

   For an example, refer to the following sample code.

   📖

   Search for Products in the Catalog

   Open Recipe

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 use keywords 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.

   For an example, refer to the following sample code.

   📖

   Search Product Types

   Open Recipe

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

   For an example, refer to the following sample code.

   📖

   Get the Schema for a Product Type

   Open Recipe

   📘

   Listing requirements

   You can list items on Amazon with or without providing offer details (sales terms) at the time of creation. For example, you can create items that are purchasable or procurable in one submission or create inactive items with sales terms that you provide later. To list an item with both product facts and sales terms, use 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 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.

   For an example, refer to the following sample code.

   📖

   Submit a Listings Item

   Open Recipe

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.

   For information about how to subscribe to notifications, refer to Subscribe to listings notifications.

   For an example, refer to the following sample code.

   📖

   Get a SKU From the Catalog

   Open Recipe

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

Offer-only listings aren't supported for vendors at this time. For all items, vendors must provide product facts and sales terms as described in 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 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.

   For an example, refer to the following sample code.

   📖

   Search for Products in the Catalog

   Open Recipe

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.

   For an example, refer to the following sample code.

   📖

   Get the Restrictions for Listing an Item

   Open Recipe

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 you should use when you list items with sales terms only.

   For an example, refer to the following sample code.

   📖

   Get the Schema for a Product Type

   Open Recipe

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.

   For an example, refer to the following sample code.

   📖

   Submit a Listings Item

   Open Recipe

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.

   For information about how to subscribe to notifications, refer to Subscribe to listings notifications.

   For an example, refer to the following sample code.

   📖

   Get a SKU From the Catalog

   Open Recipe

Preview 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

Update 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.

   For an example, refer to the following sample code.

   📖

   Get a SKU From the Catalog

   Open Recipe

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.

   For an example, refer to the following sample code.

   📖

   Get the Schema for a Product Type

   Open Recipe

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 attributes to update using the patchListingsItem operation (partial update) or by providing all listings item attributes 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). You can also add, replace, or delete attributes by 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. Essentially, you must replace the attribute data for the entire listing. For that reason, the putListingsItem operation is best suited to a full update.

   For an example, refer to the following sample code.

   📖

   Partially Update a Listings Item

   Open Recipe

   For an example, refer to the following sample code.

   📖

   Submit a Listings Item

   Open Recipe

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.

   For information about how to subscribe to notifications, refer to Subscribe to listings notifications.

   For an example, refer to the following sample code.

   📖

   Get a SKU From the Catalog

   Open Recipe

Delete 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.

For an example, refer to the following sample code.

Create and update 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 submit data in bulk with the JSON_LISTINGS_FEED, individually with the Listings Items API, or a combination of both, the volume of data that you submit impacts your overall processing time. Repeated submission of duplicate data increases your processing backlogs unnecessarily and results in longer processing times. For example, avoid resubmitting all listings for a seller in a feed submission when only one item actually changed. If you submit data only for items that have material changes, you use the available capacity most efficiently 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:

Handle 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.

Submit 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.

Configure 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.

Configure 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.

Create 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. A parent listings item must have the following attributes:

• parentage_level: value property set to parent
• child_parent_sku_relationship: child_relationship_type property set to variation
• variation_theme: name property set to a value applicable for your product

Set a listing as parent example:

  "parentage_level": [
    {
      "value": "parent"
    }
  ],
  "child_parent_sku_relationship": [
    {
      "child_relationship_type": "variation"
    }
  ],
  "variation_theme": [
    {
      "name": "SIZE/COLOR/NUMBER_OF_ITEMS"
    }
  ]

2. Follow the List an item that does not already exist in the Amazon catalog steps to create the child listings items for each unique combination of the variation family attributes. Most product facts must be replicated across all listings within the variation family. Child listing items must have the following attributes:

• parentage_level: value property set to child
• child_parent_sku_relationship: child_relationship_type property set to variation and parent_sku property set to the SKU identifier of the parent listings item
• variation_theme: name property set to the same value as the parent listing item

After you select a variation theme for a child listing item, the corresponding properties become mandatory. For example, if you set the variation_theme to SIZE/COLOR/NUMBER_OF_ITEMS, then shirt_size, color, and number_of_items become mandatory. To identify which properties become mandatory based on the selected variation theme, refer to the conditional requirements (allOf) within the Product Type Definition JSON schema.

When you select a variation_theme value for your listing, refer to enumDeprecated in $lifecycle within variation_theme. enumDeprecated indicates enumeration values that are deprecated and must be avoided. You can manage existing variation family listings that use deprecated enumeration values. However, new listings must avoid using deprecated enumeration values.

Set a listing as child example:

  "parentage_level": [
    {
      "value": "child"
    }
  ],
  "child_parent_sku_relationship": [
    {
      "child_relationship_type": "variation",
      "parent_sku": "XXXXX"
    }
  ],
  "variation_theme": [
    {
      "name": "SIZE/COLOR/NUMBER_OF_ITEMS"
    }
  ],
  "color": [
    {
      "value": "Red"
    }
  ],
  "shirt_size": [
    {
      "size_class": "age",
      "size_system": "as1",
      "size": "1_month"
    }
  ],
  "number_of_items": [
    {
      "value": 1
    }
  ]

Update or delete variation family relationship

To remove a parent-child relationship for a listing item, delete the parent or child listing. When you delete a parent listing, the relationships between the parent and all of its child listings are removed. When you delete a child listing, only the relationship between that particular child listing and its parent is removed. When you delete a relationship between a parent and a child listing, the statuses of any remaining listings are not impacted. For example, if a listing was purchasable before you delete the relationship, it remains purchasable after you delete the relationship.

You must remove a child listing from its current parent-child relationship before you relate it to a new parent.

Read variation family listings and their relationship

Use getCatalogItem /catalog/2022-04-01/items/{asin} or searchCatalogItems /catalog/2022-04-01/items and set includedData value to relationships to retrieve the relationships for the given listings.

Response example:

{
  "asin": "XXXXXX",
  "attributes": {
  ...
  },
  "relationships": [
    {
      "marketplaceId": "XXXXXX",
      "relationships": [
        {
          "parentAsins": ["XXXXXX"],
          "type": "VARIATION",
          "variationTheme": {
            "attributes": ["color", "number_of_items", "size"],
            "theme": "SIZE/COLOR/NUMBER_OF_ITEMS"
          }
        }
      ]
    }
  ]
}

Configure package hierarchies

A package hierarchy represents a collection of items for one product that is sold as individual units, in case packs, and in 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 that represents the individual sellable unit, case (inner pack) that contains the individual unit and refer to the SKU identifier of the individual unit, or pallet that contains the case and refer to 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 (inner pack) and pallet 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, use a common external product identifier for each item, only one of the items will be available for sale to buyers.
• To create a package hierarchy relationship, provide the package_level and package_contains attributes.

Set a SKU as a unit example:

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

Set 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, cases, and pallets for a product. This creates a connected listing that improves search visibility and detail page experience. For more information about Amazon Bulk Services, refer to Amazon Bulk Services: Overview on Seller Central.