Listings Items API

To learn more about the terms that are used on this page, refer to Terminology.

Use cases

The following use case examples are available for the Listings Items API:

• Retrieve details about a listing for single or multiple Amazon stores: Return detailed information about an Amazon listing for a given selling partner and single or multiple Amazon stores. The details returned can include a number of optional datasets that provide important information about the state of the listing.
• Preview errors before creating or fully updating a listing: Preview errors before creating or fully updating an Amazon listing for a given selling partner and Amazon store.
• Create or fully update a listing: Create or fully update an Amazon listing for a given selling partner and Amazon store.
• Preview errors before partially updating a listing: Preview errors before partially updating an Amazon listing for a given selling partner and Amazon store using the Listings Items API.
• Partially update a listing: Partially update an Amazon listing for a given selling partner and Amazon store using the Listings Items API.
• Merge a listing: Partially update the quantity field within the fulfillment_availability without the need to explicitly specify other optional attributes such as restock_date and lead_time_to_ship_max_days. You can also delete previously set values for quantity_discount_plan within the purchasable_offer for B2B offers. The merge operation is not supported for other attributes outside of fulfillment_availability and purchasable_offer. For granular updates to all purchasable_offer sub-attributes, refer to Manage purchasable offer.
• Delete a listing: Delete an Amazon listing for a given selling partner and Amazon store using the Listings Items API.
• Submit media attributes: Submit image and other media attributes.
• Manage purchasable offer: Update an Amazon purchasable offer for a given selling partner and Amazon store using the Listings Items API.
• Update prices for multiple Amazon stores: Submit price updates for two or more Amazon stores.
• Search for listings items by product identifier (or other listings parameters): Retrieve information about multiple listings based on SKU, ASIN, or supported product identifiers for single or multiple Amazon stores in the same region. Responses can include a number of optional datasets that provide important information about the state of a listing.

Considerations

• 1x1 updates: The Listings Items API accepts listings updates one at a time. For use-cases better suited to bulk uploads, the JSON_LISTINGS_FEED feed type can be used with the Selling Partner API for Feeds. The JSON_LISTINGS_FEED is the bulk equivalent of the Listings Items API, offering the same features and schemas provided by the Selling Partner API for Product Type Definitions.

• Fully supported product types: The Listings Items API does not yet fully support all Amazon product types. Supported Amazon product types differ by selling partner type (merchant or vendor) and by Amazon store. Refer to the Selling Partner API for Product Type Definitions for the latest available Amazon product types.

• Partially supported product types: For Amazon product types not yet fully supported by the Listings Items API, offer-only submissions for existing ASINs and partial updates are supported by using the PRODUCT product type.

• Results and issues: Responses from the Listings Items putListingsItem, patchListingsItem and deleteListingsItem operations indicate whether or not the submission was accepted for processing, along with any issues preventing the submission from being accepted. Responses do not include issues that occur after accepting the submission for processing. Responses to the Listings Items getListingsItem operation can include issues that occur after the submission has been processed.

• Attributes: The attributes section shows the latest data provided by the selling partner. Other sections, such as fulfillmentAvailability, represent the latest live data for the listing. For example, if the last inventory quantity submitted was 1 and that item is sold, the attributes section shows 1 as the latest value and the fulfillmentAvailability section shows 0 as the live quantity available for purchase.

• putListingsItem updates: The putListingsItem operation creates a new listing or replaces the existing content of a listing. Existing attributes may be dropped if omitted from the putListingsItem submission. For example, if the listing previously contained bullet points and a putListingsItem submission is made with the LISTING_OFFER_ONLY requirements without including the bullet points, the putListingsItem submission will remove the bullet points content on existing listings.

Roles for the Listings Items API v2021-08-01