Building Listings Management Workflows Guide
Integrate with SP-API to build and manage listings workflows.
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.
API reference | API Version | Use Case Guide |
---|---|---|
Catalog Items API | 2022-04-01 | Catalog Items API Use Case Guide |
Feeds API | 2021-06-30 | Feeds API Use Case Guide |
Listings Items API | 2021-08-01 | Listings Items API Use Case Guide |
Listings Restrictions API | 2021-08-01 | Listings Restrictions API Use Case Guide |
Notifications API | v1 | Notifications API Use Case Guide |
Product Type Definitions API | 2020-09-01 | Product Type Definitions API Use Case Guide |
Reports API | 2021-06-30 | Reports API Use Case Guide |
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
: TheJSON_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 thePRODUCT_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.
-
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 CatalogOpen Recipe -
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 passingitemName
, 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.For an example, refer to the following sample code.
📖Search Product TypesOpen Recipe -
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 TypeOpen RecipeListing 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 therequirements
parameter to retrieve a JSON schema with both product and offer attributes. To list an item with product facts only, useLISTING_PRODUCT_ONLY
as the value for therequirements
parameter to retrieve a JSON schema with product attributes only. -
Prepare the listing submission with attributes adhering to the JSON Schema for the product type.
-
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.
-
Call the
putListingsItem
operation to submit the listings item.For an example, refer to the following sample code.
📖Submit a Listings ItemOpen Recipe -
Inspect the response to identify if the submission status was
ACCEPTED
orINVALID
. 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. -
Wait for the
LISTINGS_ITEM_STATUS_CHANGE
orLISTINGS_ITEM_ISSUES_CHANGE
asynchronous notifications sent when the new item has been created or processing issues have occurred. Call thegetListingsItem
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 CatalogOpen 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.
-
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 CatalogOpen Recipe -
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 ItemOpen Recipe -
Call the
getDefinitionsProductType
operation to return the JSON Schema describing the attributes and constraints using thePRODUCT
product type andLISTING_OFFER_ONLY
as the value for therequirements
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 rootPRODUCT
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 TypeOpen Recipe -
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. -
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.
-
Call the
putListingsItem
operation to submit the listings item.For an example, refer to the following sample code.
📖Submit a Listings ItemOpen Recipe -
Inspect the response to identify if the submission status was
ACCEPTED
orINVALID
. 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. -
Wait for the
LISTINGS_ITEM_STATUS_CHANGE
orLISTINGS_ITEM_ISSUES_CHANGE
asynchronous notifications sent when the new item has been created or processing issues have occurred. Call thegetListingsItem
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 CatalogOpen Recipe
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.
-
Identify the selling partner SKU that needs to be updated.
-
If you need to inspect the existing attributes, then call the
getListingsItem
operation using the identified SKU. Be sure to includeattributes
andissues
in the list of values for theincludedData
parameter.For an example, refer to the following sample code.
📖Get a SKU From the CatalogOpen Recipe -
Call the
getDefinitionsProductType
operation to return the JSON Schema describing the attributes and constraints for the product type. UseLISTING
orLISTING_PRODUCT_ONLY
for therequirements
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 TypeOpen Recipe -
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. -
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.
-
Call the
patchListingsItem
orputListingsItem
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 theputListingsItem
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 thepatchListingsItem
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 thepatchListingsItem
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 thepatchListingsItem
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 theputListingsItem
operation. If you choose to use theputListingsItem
operation, you must prepopulate the request payload with the output of thegetListingsItem
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, theputListingsItem
operation is best suited to a full update.For an example, refer to the following sample code.
📖Partially Update a Listings ItemOpen RecipeFor an example, refer to the following sample code.
📖Submit a Listings ItemOpen Recipe -
Inspect the response to identify if the submission status was
ACCEPTED
orINVALID
. 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. -
Wait for the
LISTINGS_ITEM_STATUS_CHANGE
orLISTINGS_ITEM_ISSUES_CHANGE
asynchronous notifications sent when the new item has been created or processing issues have occurred. Call thegetListingsItem
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 CatalogOpen Recipe
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.
For an example, refer to the following sample code.
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?
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:
Listings Items API |
JSON_LISTINGS_FEED
|
Details | |
---|---|---|---|
Throttle rates | Five requests per second per operation (putListingsItem , patchListingsItem , deleteListingsItem ) |
One feed submission per five minutes | Each Listings Items API operation has a separate throttle rate, enabling you to submit up to five items per second for each. The JSON_LISTINGS_FEED allows one feed submission every five minutes. The JSON_LISTINGS_FEED will submit items to the Listings Items API on your behalf and is subject to the same throttling rates as submitting to the Listings Items API directly. |
Items per request | 1 | 1,500 to 10,000 | Listings Items API operations accept data for one item at a time. JSON_LISTINGS_FEED submissions can contain up to 10,000 messages. The suggested minimum feed size is 1,500 items; using the Listings Items API directly is faster with less than 1,500 items during a five-minute period. |
Validation feedback | Synchronous | Asynchronous | Listings Items API operations provide synchronous feedback during the request for issues preventing the acceptance of the data. The JSON_LISTINGS_FEED collects the feedback it receives when submitting to the Listings Items API and asynchronously provides a processing report containing the validation feedback. |
Enqueueing | Direct acceptance to the Amazon catalog | Enqueued for asynchronous acceptance to Amazon catalog | Submissions to the Listings Items API are synchronously accepted into the Amazon catalog for further processing. JSON_LISTINGS_FEED submissions are enqueued for asynchronous submission to the Listings Items API, increasing the amount of processing that occurs before submissions are accepted into the Amazon catalog for further processing. These submissions are not guaranteed to be processed in the same order that they appear in the feed. |
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:
-
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.
-
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. -
For issues that occur after acceptance of submissions to the Listings Items API or
JSON_LISTINGS_FEED
, thegetListingsItem
operation provides the list of issues when theincludedData
request parameter includesissues
. Additionally, if subscribed to theLISTINGS_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 thegetListingsItem
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:
-
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 toparent
. -
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 tochild
and referencing the SKU identifier of the parent listings item.Support for configuring variation families
Configuring variation families with the Listings Items API isn't 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 theitem_name
value used for the individual unit. For example,Pep 12oz Bottle
,Pep 12oz Bottle (Case of six)
, andPep 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
andpackage_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.
Updated 5 days ago