Listings Items API v2021-08-01 Use Case Guide

Access data on selling partner listings on Amazon.

API Version: 2021-08-01

What is the Listings Items API?

Use the Selling Partner API for Listings Items (Listings Items API) to 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. Refer to the Listings Items API Reference for details about Listings Items API operations and associated data types and schemas.

Listings data submitted to the Listings Items API adheres to the JSON Schema format provided by the Selling Partner API for Product Type Definitions. Refer to the Product Type Definitions API documentation for details on retrieving schemas for supported Amazon product types and validating data prior to submitting to Amazon with the Listings Items API.

Key features

Retrieve details about listings: The Listings Items API accepts GET operations to return detailed information about an existing listing.
Create or fully update listings: The Listings Items API accepts PUT operations to create a new listing or fully replace the data for an existing listing.
Partially update listings: The Listings Items API accepts PATCH operations to update one or more individual attributes for an existing listing, such as for updating price and quantity. Additionally, the Listings Items API accepts PATCH operations to delete one or more individual attributes for an existing listing.
Delete listings: The Listings Items API accepts DELETE operations to delete an existing listing.
Localize issue messages: The Listings Items API provides localized issue messaging either in the locale specified by the calling application or the default locale of the Amazon marketplace.
Validate submissions: The Listings Items API provides validation of submission data prior to accepting a submission for processing. Validation errors that prevent further processing are provided synchronously to the calling application.
Preview validations: Get a real-time preview of errors using the Listings Items API validation preview feature while creating or partially updating listings. This allows you to preview errors synchronously without persisting data to the catalog.

Terminology

Listing: An Amazon listing is an item that a selling partner has listed for sale on Amazon and is identified by a SKU. Product facts included in Amazon listings are reconciled into Amazon catalog items, which are identified by Amazon Standard Identification Numbers (ASINs).
Full update: A full update to an Amazon listing results in full data requirements validation on the submitted data and either creates a new listing or replaces the data for an existing listing.
Partial update: A partial update to an Amazon listing results in partial data requirements validation for the attributes provided and updates one or more attributes for an existing listing.
Product type: An Amazon product type is a hierarchal categorization of items in the Amazon catalog. Item data requirements are tied to the associated product type of the item.

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

🚧
Handling generic JSON schemas in client libraries
If you have generated a client library, it is important to note that Swagger Codegen generates types based on properties defined in the Swagger models, and that Swagger Codegen will produce empty or incomplete types when an object is defined with additionalProperties: true. To handle such objects, use the --import-mappings command-line parameter to map these objects to a generic JSON object type or a custom object type of your choosing.
Example Swagger Codegen input parameters:
C#: --import-mappings ItemAttributes=Newtonsoft.Json.Linq.JObject
Java: --import-mappings ItemAttributes=com.google.gson.JsonObject

Tutorial: Retrieve details about a listing

Use this tutorial to return detailed information about an Amazon listing for a given selling partner and Amazon marketplace. The details returned can include a number of optional datasets that provide important information about the state of the listing.

🚧
Important
The new LISTINGS_ITEM_STATUS_CHANGE notification mentioned in the following paragraphs is available only to sellers. The LISTINGS_ITEM_ISSUES_CHANGE notification is available to sellers and vendors.

For example, if you have subscribed to receive the LISTINGS_ITEM_ISSUES_CHANGE notification using the Selling Partner API for Notifications (Notifications API) and you receive the notification, you can call the getListingsItem operation of the Listings Item API to get more details. The LISTINGS_ITEM_ISSUES_CHANGE notification does not include the same level of detailed information about issues as does the API. To return more detailed information, call getListingsItem and specify issues in the includedData parameter to get the issues dataset.

Similarly, if you subscribe to the LISTINGS_ITEM_STATUS_CHANGE notification using the Notifications API and you receive the notification, you can call the getListingsItem operation to receive more detailed info. For example, if a listing ceases to be DISCOVERABLE as indicated in the notification, you might want to get the issues dataset to determine the reason for the search suppression.

For another example, if the LISTINGS_ITEM_STATUS_CHANGE notification does not indicate that the listing is buyable (Status does not include BUYABLE), a common reason could be a lack of inventory. In that case, call the getListingsItem operation and include fulfillmentAvailability in the includedData parameter to return the fulfillmentAvailability dataset.

In general, the datasets available via the includedData parameter will help you better understand the status of the listing. The datasets available include summary information, contributed attributes, issues, offer information (sellers), fulfillment availability (sellers), and procurement details (vendors).

Prerequisites

To complete this tutorial, you need:

Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
Approval for the Product Listing role in your developer profile.
The Product Listing role selected in the App registration page for your application.

Step 1: Submit listings item GET request

Call the getListingsItem operation to return details about a listings item, passing the following parameters:

Path parameters

Parameter	Example	Description	Required
`sellerId`	`AXXXXXXXXXXXXX`	A selling partner identifier, such as a merchant account or vendor code. Type: string	Yes
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string	Yes

Query parameters

Parameter	Example	Description	Required
`marketplaceIds`	`ATVPDKIKX0DER`	The marketplace ID is the globally unique identifier of a marketplace. To find the ID for your marketplace, refer to Marketplace IDs. Type: string	Yes
`issueLocale`	`en_US`	Locale for issue localization. Default: When you don't specify a locale, the default locale of the first marketplace is used. Localization defaults to `en_US` when a localized message is not available in the specified locale. Type: string	No
`includedData`	`summaries`	A comma-delimited list of datasets that you can include in the response. Default: summaries. Type: < enum (IncludedData) > array(csv)	No

Request example

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/50-TS3D-QEPT
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &includedData=issues,attributes,summaries,offers,fulfillmentAvailability

Response

A successful response includes one or more of the following:

Name	Example	Description
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string
`summaries`	Refer to response example	Summary details of a listings item. Type: ItemSummaries
`attributes`	Refer to response example	JSON object that contains structured listings item attribute data keyed by attribute name. Type: ItemAttributes
`issues`	Refer to response example	Issues associated with the listings item. Type: ItemIssues
`offers`	Refer to response example	Offer details for the listings item. Type: ItemOffers
`fulfillmentAvailability`	Refer to response example	Fulfillment availability for the listings item. Type: < FulfillmentAvailability > array
`procurement`	Refer to response example	Vendor procurement information for the listings item. Type: ItemProcurement

Response examples

Example response for a seller (merchant) that includes the summaries, attributes, issues, offers, and fulfillmentAvailability datasets.

{
  "sku": "50-TS3D-QEPT",
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B08YRD1CNN",
      "productType": "DRINKING_CUP",
      "conditionType": "new_new",
      "status": [
        "BUYABLE",
        "DISCOVERABLE"
      ],
      "itemName": "6 Pack Coffee Mug Set, Farielyn-X 16 Ounce Ceramic Coffee Cups, Black Large Coffee mugs, Restaurant Coffee Cups for Coffee, Tea, Cappuccino, Cocoa, Cereal, Matte Black Outside and Colorful Inside",
      "createdDate": "2021-07-14T19:57:02.327Z",
      "lastUpdatedDate": "2021-07-14T19:57:10.637Z",
      "mainImage": {
        "link": "https://m.media-amazon.com/images/I/41epVg7mZoS.jpg",
        "height": 500,
        "width": 500
      }
    }
  ],
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_shipping_group": [
      {
        "value": "legacy-template-id",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "B08YRD1CNN",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "purchasable_offer": [
      {
        "audience": "ALL",
        "currency": "USD",
        "start_at": {
          "value": "2021-07-14T19:56:57.717Z"
        },
        "our_price": [
          {
            "schedule": [
              {
                "value_with_tax": 30.0
              }
            ]
          }
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "audience": "B2B",
        "currency": "USD",
        "marketplace_id": "ATVPDKIKX0DER",
        "our_price": [
          {
            "schedule": [
              {
                "value_with_tax": 28.0
              }
            ]
          }
        ],
        "quantity_discount_plan": [
          {
            "schedule": [
              {
                "discount_type": "percent",
                "levels": [
                  {
                    "lower_bound": 5,
                    "value": 25.0
                  },
                  {
                    "lower_bound": 10,
                    "value": 20.0
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "fulfillment_availability": [
      {
        "fulfillment_channel_code": "DEFAULT",
        "quantity": 1,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "main_product_image_locator": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxx1.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "other_product_image_locator_1": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx2.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "other_product_image_locator_2": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx3.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ]
  },
  "issues": [
    {
      "code": "18448",
      "message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): item_weight, theme, item_dimensions, item_diameter",
      "severity": "WARNING",
      "attributeNames": [
        "item_diameter",
        "item_dimensions",
        "item_weight",
        "theme"
      ],
      "categories": [
        "MISSING_ATTRIBUTE"
      ]
    },
    {
      "code": "18027",
      "message": "We believe the main image has text, logo, graphic or watermark which is not permitted for this product type. Please submit a compliant image to lift the suppression. Also refer to Product image requirements.",
      "severity": "ERROR",
      "categories": [
        "INVALID_IMAGE"
      ],
      "enforcements": {
        "actions": [
          {
            "action": "SEARCH_SUPPRESSED"
          }
        ],
        "exemption": {
          "status": "EXEMPT_UNTIL_EXPIRY_DATE",
          "expiryDate": "2025-05-28T00:36:48.914Z"
        }
      }
    },
    {
      "code": "99300",
      "message": "Product Detail Page Rules Violation (Inaccurate information on product detail page)",
      "severity": "ERROR",
      "categories": [],
      "enforcements": {
        "actions": [
          {
            "action": "ATTRIBUTE_SUPPRESSED"
          }
        ],
        "exemption": {
          "status": "EXEMPT"
        }
      }
    },
    {
      "code": "18155",
      "message": "The 'minimum price' is greater than the selling price (excluding shipping) for the listing. Please review and update your price and/or minimum price.",
      "severity": "ERROR",
      "categories": [
        "INVALID_PRICE"
      ],
      "enforcements": {
        "actions": [
          {
            "action": "LISTING_SUPPRESSED"
          }
        ],
        "exemption": {
          "status": "NOT_EXEMPT"
        }
      }
    },
    {
      "code": "18742",
      "message": "Restricted Products Policy Violation",
      "severity": "ERROR",
      "categories": [],
      "enforcements": {
        "actions": [
          {
            "action": "CATALOG_ITEM_REMOVED"
          }
        ],
        "exemption": {
          "status": "NOT_EXEMPT"
        }
      }
    }
  ],
  "offers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "offerType": "B2C",
      "price": {
        "currency": "USD",
        "amount": "30.0"
      },
      "audience": {
        "value": "ALL",
        "displayName": "Sell on Amazon"
      }
    },
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "offerType": "B2B",
      "price": {
        "currency": "USD",
        "amount": "28.0"
      },
      "audience": {
        "value": "B2B",
        "displayName": "Amazon Business (B2B)"
      }
    }
  ],
  "fulfillmentAvailability": [
    {
      "fulfillmentChannelCode": "DEFAULT",
      "quantity": 1
    }
  ]
}

Request example

Example request and response for a vendor that includes summaries, procurement, and issues datasets.

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/example-sku
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &includedData=summaries,procurement,issues

Response example

{
  "sku": "example-sku",
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B071VG5N9D",
      "productType": "LUGGAGE",
      "conditionType": "new_new",
      "status": [
        "DISCOVERABLE"
      ],
      "itemName": "Hardside Carry-On Spinner Suitcase Luggage",
      "createdDate": "2021-02-01T00:00:00Z",
      "lastUpdatedDate": "2021-03-01T00:00:00Z",
      "mainImage":
      {
        "link": "https://www.example.com/luggage.png",
        "height": 500,
        "width": 500
      }
    }
  ],
  "procurement": [
    {
      "costPrice":
      {
        "currencyCode": "USD",
        "amount": "100.00"
      }
    }
  ],
  "issues": [
    {
      "code": "18448",
      "message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): item_weight, theme, item_dimensions, item_diameter",
      "severity": "WARNING",
      "attributeNames": [
        "item_diameter",
        "item_dimensions",
        "item_weight",
        "theme"
      ],
      "categories": ["MISSING_ATTRIBUTE"]
    },
    {
      "code": "18027",
      "message": "We believe the main image has text, logo, graphic or watermark which is not permitted for this product type. Please submit a compliant image to lift the suppression. Also refer to Product image requirements.",
      "severity": "ERROR",
      "categories": ["INVALID_IMAGE"],
      "enforcements": {
        "actions": [
          {
            "action": "SEARCH_SUPPRESSED"
          }
        ],
        "exemption": {
          "status": "EXEMPT_UNTIL_EXPIRY_DATE",
          "expiryDate": "2025-05-28T00:36:48.914Z"
        }
      }
    },
    {
      "code": "99300",
      "message": "Product Detail Page Rules Violation (Inaccurate information on product detail page)",
      "severity": "ERROR",
      "categories": [],
      "enforcements": {
        "actions": [
          {
            "action": "ATTRIBUTE_SUPPRESSED"
          }
        ],
        "exemption": {
          "status": "EXEMPT"
        }
      }
    },
    {
      "code": "18742",
      "message": "Restricted Products Policy Violation",
      "severity": "ERROR",
      "categories": [],
      "enforcements": {
        "actions": [
          {
            "action": "CATALOG_ITEM_REMOVED"
          }
        ],
        "exemption": {
          "status": "NOT_EXEMPT"
        }
      }
    }
  ]
}

Tutorial: Preview errors before creating or fully updating a listing

Use this tutorial to preview errors before creating or fully updating an Amazon listing for a given selling partner Amazon marketplace.

Prerequisites

To complete this tutorial, you need:

Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
Approval for the Product Listing role in your developer profile.
The Product Listing role selected in the App registration page for your application.
A JSON-based listing payload adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions for the given selling partner, Amazon marketplace, and Amazon product type.

Step 1. Preview errors for a listings item PUT request

To preview the results after you create or fully update a listing, call the putListingsItem operation and pass the following parameters:

Path parameters

Parameter	Example	Description	Required
`sellerId`	`AXXXXXXXXXXXXX`	A selling partner identifier, such as a merchant account or vendor code. Type: string	Yes
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string	Yes

Query parameters

Parameter	Example	Description	Required
`marketplaceIds`	`ATVPDKIKX0DER`	The marketplace ID is the globally unique identifier of a marketplace. To find the ID for your marketplace, refer to [Marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids). Type: string	Yes
`issueLocale`	`en_US`	Locale for issue localization. Default: When no locale is provided, the default locale of the first marketplace is used. Localization defaults to `en_US` when a localized message is not available in the specified locale. Type: string	No
`mode`	`VALIDATION_PREVIEW`	Describes the mode of operation for the request. Type: enum (`Mode`)	No
`includedData`	`issues`	A comma-delimited list of datasets to include in the response. Default: `issues` Type: < enum (`IncludedData`) > array (csv)	No

Body parameters

Parameter	Example	Description	Required
`body`	Refer to example request	The request body schema for the `putListingsItem` operation. Type: `ListingsItemPutRequest`	Yes

Request example

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &mode=VALIDATION_PREVIEW
  &includedData=issues,identifiers

Response

A successful response includes the following:

Name	Example	Description
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string
`status`	`VALID`	Status of the listings item submission. Type: enum(`Status`)
`submissionId`	`65793a6142784e36b39af92b736a3a9f`	Unique identifier of the listings item submission. Type: string
`asin`	`BXXXXXXXXX`	Amazon Standard Identification Number (ASIN) of the listings item. Type: string
`issues`	Refer to Example Response	Listings item issues related to the listings item submission. Type < `Issue` > array

Response example

{
  "sku": "ABC123",
  "status": "VALID",
  "submissionId": "65793a6142784e36b39af92b736a3a9f",
  "issues": [],
  "identifiers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B987654321"
    }
  ]
}

Tutorial: Create or fully update a listing

Use this tutorial to create or fully update an Amazon listing for a given selling partner and Amazon marketplace.

Prerequisites

To complete this tutorial, you need:

Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
Approval for the Product Listing role in your developer profile.
The Product Listing role selected in the App registration page for your application.
A JSON-based listing payload adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions for the given selling partner, Amazon marketplace, and Amazon product type.

Step 1. Submit listings item put request

Call the putListingsItem operation to create or fully update a listing, passing the following parameters:

Path parameters

Parameter	Example	Description	Required
`sellerId`	`AXXXXXXXXXXXXX`	A selling partner identifier, such as a merchant account or vendor code. Type: string	Yes
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string	Yes

Query parameters

Parameter	Example	Description	Required
`marketplaceIds`	`ATVPDKIKX0DER`	The marketplace ID is the globally unique identifier of a marketplace. To find the ID for your marketplace, refer to [Marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids). Type: string	Yes
`issueLocale`	`en_US`	Locale for issue localization. Default: When no locale is provided, the default locale of the first marketplace is used. Localization defaults to `en_US` when a localized message is not available in the specified locale. Type: string	No
`mode`	`VALIDATION_PREVIEW`	Describes the mode of operation for the request. Type: enum (`Mode`)	No
`includedData`	`issues`	A comma-delimited list of datasets to include in the response. Default: `issues` Type: < enum (`IncludedData`) > array (csv)	No

Body parameter

Parameter	Example	Description	Required
`body`	Refer to Example Request	The request body schema for the putListingsItem operation. Type: `ListingsItemPutRequest`	Yes

Request example

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
    ?marketplaceIds=ATVPDKIKX0DER
    &issueLocale=en_US

{
  "productType": "LUGGAGE",
  "requirements": "LISTING",
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_name": [
      {
        "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
        "language_tag": "en_US",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    ...
  }
}

Response

A successful response includes the following:

Name	Example	Description
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string
`status`	`ACCEPTED`	Status of the listings item submission. Type: enum(`Status`)
`submissionId`	`f1dc291475dd11eabc550242ac130003`	Unique identifier of the listings item submission. Type: string
`issues`	Refer to Example Response	Listings item issues related to the listings item submission. Type < `Issue` > array

Response example

{
  "sku": "ABC123",
  "status": "INVALID",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": [
    {
      "code": "90220",
      "message": "'product_description' is required but not supplied.",
      "severity": "ERROR",
      "attributeNames": [
        "product_description"
      ],
      "categories": ["MISSING_ATTRIBUTE"]
    }
    ...
  ]
}

Tutorial: Preview errors before partially updating a listing

Use this tutorial to preview errors before partially updating an Amazon listing for a given selling partner and Amazon marketplace using the Listings Items API.

Partial updates are submitted in the form of JSON Patch documents. Refer to JSON Object Notation Patch for more details about JSON Patch documents. For Amazon listings, JSON Patch documents can add, replace, or delete entire attributes. Patching content within attributes is not supported.

Prerequisites

To complete this tutorial, you need:

Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
Approval for the Product Listing role in your developer profile.
The Product Listing role selected in the App registration page for your application.
For attribute updates, JSON-based listing attribute payloads adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions for the given selling partner, Amazon marketplace, Amazon product type, and attributes.
For attribute deletes, JSON-based listing attribute payloads adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions for the given selling partner, Amazon marketplace, Amazon product type, and attributes with the selector properties of the attributes to delete. Attributes cannot be deleted by name alone. The selector values identify which instance of attributes to delete.

Step 1. Preview errors for a listings item patch request

Call the patchListingsItem operation to partially update a listing, passing the following parameters:

Path parameters

Parameter	Example	Description	Required
`sellerId`	`AXXXXXXXXXXXXX`	A selling partner identifier, such as a merchant account or vendor code. Type: string	Yes
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string	Yes

Query parameters

Parameter	Example	Description	Required
`maketplaceIds`	`ATVPDKIKX0DER`	Comma-delimited list of Amazon marketplace identifiers. Refer to Marketplace IDs for the list of Amazon marketplace identifiers. Type: < string > array(csv)	Yes
`issueLocale`	`en_US`	Locale for issue localization. Default: When no locale is provided, the default locale of the first marketplace is used. Localization defaults to `en_US` when a localized message is not available in the specified locale. Type: string	No
`mode`	`VALIDATION_PREVIEW`	Describes the mode of operation for the request. Type: enum (`Mode`)	No
`includedData`	`issues`	A comma-delimited list of datasets to include in the response. Default: `issues` Type: < enum (`IncludedData`) > array (csv)	No

Body parameters

Parameter	Example	Description	Required
`body`	Refer to example request	The request body schema for the `patchListingsItem` operation. Type: `ListingsItemPatchRequest`	Yes

Request example

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &mode=VALIDATION_PREVIEW
  &includedData=issues,identifiers

Response

A successful reponse includes the following:

Name	Example	Description
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string
`status`	`VALID`	Status of the listings item submission. Type: enum(`Status`)
`submissionId`	`65793a6142784e36b39af92b736a3a9f`	Unique identifier of the listings item submission. Type: string
`asin`	`BXXXXXXXXX`	Amazon Standard Identification Number (ASIN) of the listings item. Type: string
`issues`	Refer to Example Response	Listings item issues related to the listings item submission. Type < `Issue` > array

Reponse example


{
  "sku": "ABC123",
  "status": "VALID",
  "submissionId": "65793a6142784e36b39af92b736a3a9f",
  "issues": [],
  "identifiers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B987654321"
    }
  ]
}

Tutorial: Partially update a listing

Use this tutorial to partially update an Amazon listing for a given selling partner and Amazon marketplace using the Listings Items API.

Partial updates are submitted in the form of JSON Patch documents. Refer to https://tools.ietf.org/html/rfc6902 for more details about JSON Patch documents. For Amazon listings, JSON Patch documents can add, replace, or delete entire attributes. Patching content within attributes is not supported.

Prerequisites

To complete this tutorial, you need:

Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
Approval for the Product Listing role in your developer profile.
The Product Listing role selected in the App registration page for your application.
For attribute updates, JSON-based listing attribute payloads adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions for the given selling partner, Amazon marketplace, Amazon product type, and attributes.
For attribute deletes, JSON-based listing attribute payloads adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions for the given selling partner, Amazon marketplace, Amazon product type, and attributes with the selector properties of the attributes to delete. Attributes cannot be deleted by name alone, the selector values identify which instance of attributes to delete.

Step 1. Submit listings item patch request

Call the patchListingsItem operation to partially update a listing, passing the following parameters:

Path parameters

Parameter	Example	Description	Required
`sellerId`	`AXXXXXXXXXXXXX`	A selling partner identifier, such as a merchant account or vendor code. Type: string	Yes
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string	Yes

Query parameters

Parameter	Example	Description	Required
`marketplaceIds`	`ATVPDKIKX0DER`	The marketplace ID is the globally unique identifier of a marketplace. To find the ID for your marketplace, refer to [Marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids). Type: string	Yes
`issueLocale`	`en_US`	Locale for issue localization. Default: When no locale provided, the default locale of the first marketplace is used. Localization defaults to `en_US` when a localized message is not available in the specified locale. Type: string	No
`mode`	`VALIDATION_PREVIEW`	Describes the mode of operation for the request. Type: enum (`Mode`)	No
`includedData`	`issues`	A comma-delimited list of datasets to include in the response. Default: `issues` Type: < enum (`IncludedData`) > array (csv)	No

Body parameter

Parameter	Example	Description	Required
`body`	Refer to Example Request	The request body schema for the `patchListingsItem` operation. Type: `ListingsItemPatchRequest`	Yes

Request example

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
	?marketplaceIds=ATVPDKIKX0DER
	&issueLocale=en_US

{
  "productType":"LUGGAGE",
  "patches":[
    {
      "op":"replace",
      "path":"/attributes/item_name",
      "value":[
        {
          "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
          "language_tag": "en_US",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    },
    {
      "op":"replace",
      "path":"/attributes/purchasable_offer",
      "value":[
        {
          "audience": "ALL",
          "marketplace_id": "ATVPDKIKX0DER",
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 15.00
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "op":"delete",
      "path":"/attributes/item_type_name",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "language_tag": "en_US"
        }
      ]
    }
  ]
}

Response

A successful response includes the following:

Name	Example	Description
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string
`status`	`ACCEPTED`	Status of the listings item submission. Type: enum(`Status`)
`submissionId`	`f1dc291475dd11eabc550242ac130003`	Unique identifier of the listings item submission. Type: string
`issues`	Refer to Example Response	Listings item issues related to the listings item submission. Type < `Issue` > array

Response example

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": []
}

Tutorial: Delete a listing

Use this tutorial to delete an Amazon listing for a given selling partner and Amazon marketplace using the Listings Items API.

The following diagram provides an overview of the workflow steps to delete a listing item.

The workflow chart of interactions between the user and Selling Partner API to delete a listing item.

Prerequisites

To complete this tutorial, you need:

Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
Approval for the Product Listing role in your developer profile.
The Product Listing role selected in the App registration page for your application.

Step 1. Submit listings item delete request

Call the deleteListingsItem operation to delete a listing, passing the following parameters:

Path parameters

Parameter	Example	Description	Required
`sellerId`	`AXXXXXXXXXXXXX`	A selling partner identifier, such as a merchant account or vendor code. Type: string	Yes
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string	Yes

Query parameters

Parameter	Example	Description	Required
`marketplaceIds`	`ATVPDKIKX0DER`	The marketplace ID is the globally unique identifier of a marketplace. To find the ID for your marketplace, refer to [Marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids). Type: string	Yes
`issueLocale`	`en_US`	Locale for issue localization. Default: When no locale provided, the default locale of the first marketplace is used. Localization defaults to `en_US` when a localized message is not available in the specified locale. Type: string	No

Request example

DELETE https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
    ?marketplaceIds=ATVPDKIKX0DER
    &issueLocale=en_US

Response

A successful response includes the following:

Name	Example	Description
`sku`	`ABC123`	Identifier (SKU) of the listings item that is unique to the selling partner. Type: string
`status`	`ACCEPTED`	Status of the listings item submission. Type: enum(`Status`)
`submissionId`	`f1dc291475dd11eabc550242ac130003`	Unique identifier of the listings item submission. Type: string
`issues`	Refer to Example Response	Listings item issues related to the listings item submission. Type < `Issue` > array

Response Example

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": []
}

Submitting images and other media attributes

The Listings Items API accepts product images and other media content attributes from the following sources:

Publicly accessible Amazon S3 bucket content downloaded through HTTP or HTTPS URL
Publicly accessible Amazon CloudFront distribution content downloaded through HTTP or HTTPS URL
Private Amazon S3 bucket content downloaded through S3 URL (for example, s3://bucket-name/object-name.jpg)
Images hosted on third-party servers that are publicly available to Amazon.

⭐
Tip
For optimal processing performance, host your media on AWS (such as Amazon S3 or Amazon CloudFront) or other highly available content delivery network (CDN) services.
If you use a private Amazon S3 bucket, you must also configure your Amazon S3 bucket policy to allow the IAM role (arn:aws:iam:111122223333:role/Media-Download-Role) to call the GetObject and ListBucket operations on the bucket. Refer to the following S3 bucket policy for an example.

Private Amazon S3 content is treated as immutable, meaning you cannot change the content for an Amazon S3 object key. New media content requires a new Amazon S3 object key. This convention provides the benefit of improved processing times and avoids the cost of redundant downloads in case listing submissions are re-processed.

The following is an example Amazon S3 bucket policy enabling the required operations on a bucket named bucket-name:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::bucket-name/*",
        "arn:aws:s3:::bucket-name"
      ],
      "Principal": {
        "AWS": [
          "arn:aws:iam::368641386589:role/Media-Download-Role"
        ]
      }
    }
  ]
}

Tutorial: Search for listings items by product identifier (or other listings parameters)

Learn how to retrieve information about multiple listings based on SKU, ASIN, or supported product identifiers. Responses can include a number of optional datasets that provide important information about the state of a listing.

❗
Warning
SP-API cannot distinguish encoded commas (%2C) from literal commas (,). This means that you can't include SKUs that contain commas within comma-delimited queries, because commas in SKUs cannot be distinguished from commas that separate arguments.
When a SKU contains a comma, you must search for the SKU individually. For more information, refer to How do I encode a URL?

Even though there can be more than 1,000 SKUs that match the search criteria, the maximum number of results that can be returned and paged through is limited to 1,000. For example, if you set the pageSize to 10, the maximum number of possible pages is 100.

Prerequisites

To complete this tutorial, you need:

Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
Approval for the Product Listing role in your developer profile.
The Product Listing role selected in the App registration page for your application.

Submit a listings item search request

To return details for multiple listings items, call the searchListingsItem operation and pass the following parameters:

Path parameters

Parameter	Example	Description	Required
`sellerId`	`AXXXXXXXXXXXXX`	A selling partner identifier, such as a merchant account or vendor code. Type: string	Yes

Query parameters

Parameter	Example	Description	Required
`marketplaceIds`	`ATVPDKIKX0DER`	Comma-delimited list of Amazon marketplace identifiers. Type: < string > array(csv)	Yes
`identifiers`	`GM-ZDPI-9B4E`	Comma-delimited list of product identifiers used to search for listings items. Required when `identifiersType` is provided. Don't use when `variationParentSku` or `packageHierarchySku` are provided.	No
`identifiersType`	`SKU`	Type of product identifiers used to search for listings items. Required when `identifiers` is provided. Type: enum (`IdentifiersType`)	No
`variationParentSku`	`GM-ZDPI-9B4E`	Filter results to include listing items that are variation children of the provided SKU. Invalid when `identifiers` or `packageHierarchySku` are provided. Type: <string>	No
`packageHierarchySku`	`GM-ZDPI-9B4E`	Filter results to include listing items that contain or are contained by the provided SKU. Invalid when `identifiers` or `variationParentSku` are provided. Type: <string>	No
`createdAfter`	`2024-03-01T01:30:00.000Z`	Date in ISO 8601 format to filter listing items that were created after. Type: <string> Format: <date-time>	No
`createdBefore`	`2024-03-31T21:45:00.000Z`	Date in ISO 8601 format to filter listing items that were created before. Type: <string> Format: <date-time> No
`lastUpdatedAfter`	`2024-05-05T23:45:00.000Z`	Date in ISO 8601 format to filter listings that were last updated after. Type: <string> Format: <date-time>	No
`lastUpdatedBefore`	`2024-05-01T01:15:00.000Z`	Date in ISO 8601 format to filter listings that were last updated before. Type: <string> Format: <date-time>	No
`withIssueSeverity`	`WARNING`	Filter results down to include listing items that have issues that match one or more of the severity levels in this list. Type: enum <Severity> array(csv)	No
`withStatus`	`DISCOVERABLE`	Filter results down to listing items that have one of the statuses in this list. Type: enum array(csv)	No
`withoutStatus`	`BUYABLE`	Filter results down to listing items that don't have any of the statuses in this list. Type: enum array(csv)	No
`sortBy`	`lastUpdatedDate`	Attribute by which the result listing items are sorted. Type: enum	No
`sortOrder`	`DESC`	Order in which you want the result items sorted. Type: enum	No
`issueLocale`	`en_US`	Locale for issue localization. Default: The locale of the first marketplace. When a localization isn't available in the specified locale, the default is `en_US`. Type: string	No
`includedData`	`summaries`	A comma-delimited list of datasets that you can include in the response. Default: summaries. Type: < enum (IncludedData) > array(csv)	No
`pageSize`	--	Number of results you want returned per page. Maximum: 20; Default: 10	No
`pageToken`	--	A token that is used to fetch a certain page when there are multiple pages of results. Note: The encode token is returned in the response.	No

📘
Note
If you use packageHierarchySku with a family size that exceeds 20 SKUs, only the first 20 SKUs are returned in the response.

You can use sortBy and sortOrder to sort your results.

Include any IncludedData values that you want in your response.

Value	Description
`summaries`	Summary details of the listing item
`attributes`	A JSON object containing structured listing item attribute data keyed by attribute name
`issues`	The issues associated with the listing item
`offers`	The current offers for the listing item
`fulfillmentAvailability`	The fulfillment availability details for the listing item
`procurement`	The vendor procurement details for the listing item
`relationships`	Relationship details of an listing item (for example, variations)
`productTypes`	Product types associated with a listing item

Request Example

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX?marketplaceIds=ATVPDKIKX0DER 
&identifiers=XXXXXXXXX,YYYYYYYY,ZZZZZZZZ 
&identifiersType=SKU 
&issueLocale=en_US 
&includedData=issues,attributes,summaries
&pageSize=20

Response

A successful response includes:

Name	Type	Description
`numberOfResults`	integer	The total number of products that are matched by the search query. Only results up to the page count limit are returned per request.
`pagination`	pagination	A JSON object that contains one or more page tokens, which you can used to fetch the next (or previous) page of results.
`items`	< item > array	A list of Selling Partner listings items. The information included for each item depends on the specified value for `includedData`.

Response example

{
    "numberOfResults": 3,
    "pagination": {
        "nextToken": "xsdflkj324lkjsdlkj3423klkjsdfkljlk2j34klj2l3k4jlksdjl234",
        "previousToken": "ilkjsdflkj234lkjds234234lkjl234lksjdflkj234234lkjsfsdflkj333d"
    },
    "items": [
        {
            "sku": "GM-ZDPI-9B4E",
            "summaries": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "asin": "B071VG5N9D",
                    "productType": "LUGGAGE",
                    "conditionType": "new_new",
                    "status": [
                        "BUYABLE"
                    ],
                    "itemName": "Hardside Carry-On Spinner Suitcase Luggage",
                    "createdDate": "2021-02-01T00:00:00Z",
                    "lastUpdatedDate": "2021-03-01T00:00:00Z",
                    "mainImage": {
                        "link": "https://www.example.com/luggage.png",
                        "height": 500,
                        "width": 500
                    }
                }
            ],
            "offers": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "offerType": "B2C",
                    "price": {
                        "currencyCode": "USD",
                        "amount": "100.00"
                    }
                }
            ],
            "fulfillmentAvailability": [
                {
                    "fulfillmentChannelCode": "DEFAULT",
                    "quantity": 100
                }
            ],
            "issues": [
                {
                    "code": "90220",
                    "message": "'size' is required but not supplied.",
                    "severity": "ERROR",
                    "attributeNames": [
                        "size"
                    ],
                    "categories": [
                        "MISSING_ATTRIBUTE"
                    ]
                },
                {
                   "code": "18027",
                    "message": "We believe the main image has text, logo, graphic or watermark which is not permitted for this product type. Please submit a compliant image to lift the suppression. Also refer to Product image requirements.",
                    "severity": "ERROR",
                    "categories": [
                        "INVALID_IMAGE"
                    ],
                    "enforcements": {
                        "actions": [
                            {
                                "action": "SEARCH_SUPPRESSED"
                            }
                        ],
                        "exemption": {
                            "status": "EXEMPT_UNTIL_EXPIRY_DATE",
                            "expiryDate": "2025-05-28T00:36:48.914Z"
                        }
                    }
                },
                {
                    "code": "99300",
                    "message": "Product Detail Page Rules Violation (Inaccurate information on product detail page)",
                    "severity": "ERROR",
                    "categories": [],
                    "enforcements": {
                        "actions": [
                            {
                                "action": "ATTRIBUTE_SUPPRESSED"
                            }
                        ],
                        "exemption": {
                            "status": "EXEMPT"
                        }
                    }
                },
                {
                    "code": "18155",
                    "message": "The 'minimum price' is greater than the selling price (excluding shipping) for the listing. Please review and update your price and/or minimum price.",
                    "severity": "ERROR",
                    "categories": [
                        "INVALID_PRICE"
                        ],
                    "enforcements": {
                        "actions": [
                            {
                                "action": "LISTING_SUPPRESSED"
                            }
                        ],
                        "exemption": {
                            "status": "NOT_EXEMPT"
                        }
                    }
                },
                {
                    "code": "18742",
                    "message": "Restricted Products Policy Violation",
                    "severity": "ERROR",
                    "categories": [],
                    "enforcements": {
                        "actions": [
                            {
                                "action": "CATALOG_ITEM_REMOVED"
                            }
                        ],
                        "exemption": {
                            "status": "NOT_EXEMPT"
                        }
                    }
                }
            ]
        }
    ]
}

Updated 12 days ago

What is the Listings Items API?

Key features

Terminology

Considerations

🚧Handling generic JSON schemas in client libraries

Tutorial: Retrieve details about a listing

🚧Important

Prerequisites

Step 1: Submit listings item GET request

Path parameters

Query parameters

Request example

Response

Response examples

Request example

Response example

Tutorial: Preview errors before creating or fully updating a listing

Prerequisites

Step 1. Preview errors for a listings item PUT request

Path parameters

Query parameters

Body parameters

Request example

Response

Response example

Tutorial: Create or fully update a listing

Prerequisites

Step 1. Submit listings item put request

Path parameters

Query parameters

Request example

Response

Response example

Tutorial: Preview errors before partially updating a listing

Prerequisites

Step 1. Preview errors for a listings item patch request

Path parameters

Query parameters

Body parameters

Request example

Response

Reponse example

Tutorial: Partially update a listing

Prerequisites

Step 1. Submit listings item patch request

Path parameters

Query parameters

Request example

Response

Response example

Tutorial: Delete a listing

Prerequisites

Step 1. Submit listings item delete request

Path parameters

Query parameters

Request example

Response

Response Example

Submitting images and other media attributes

⭐Tip

Tutorial: Search for listings items by product identifier (or other listings parameters)

❗Warning

Prerequisites

Submit a listings item search request

Path parameters

Query parameters

📘Note

Request Example

Response

Response example

🚧
Handling generic JSON schemas in client libraries

🚧
Important

⭐
Tip

❗
Warning

📘
Note