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

📘

Note

The getListingsItem operation supports multiple marketplaceIds values within the same region in a single request. Previously, you could specify only a single marketplaceIds value per request. Single-value requests continue to work as before.

The marketplaceIds parameter accepts a maximum of 12 Amazon stores per request.

This feature is available for sellers only. This feature does not support vendor accounts because each vendor code is associated with a single Amazon store.

📘

Primary marketplaceIds behavior

When you provide multiple marketplaceIds values, the operation treats the first value in the array as the primary Amazon store. Primary Amazon store behavior depends on the search type:

• SKU-based searches (identifier type SKU): When no additional filter conditions (such as withStatus) are applied, the operation returns results for all requested SKUs in all requested Amazon stores regardless of the primary Amazon store. When additional filter conditions are applied, the operation evaluates filtering and sorting against the primary Amazon store only.

• All other search types (identifier types such as EAN, UPC, or filter and sort parameters like withStatus or sortBy): The operation evaluates filtering and sorting against the primary Amazon store only. The response includes results for additional Amazon stores without applying those filters.

For example, if you search with withStatus=BUYABLE, sortBy=createdDate, and marketplaceIds=ATVPDKIKX0DER,A2EUQ1WTGCTBG2,A1AM78C64UM0Y8 (US, CA, MX), the operation returns only SKUs that are BUYABLE in the Amazon US store, sorted by their US creation date. For each matching SKU, the response also includes data from CA and MX regardless of their status in those Amazon stores.

❗

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 across single or multiple Amazon stores in the same region, call the searchListingsItems operation.

📘

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.

Pagination token expiration

The token returned in the nextToken field expires 24 hours after generation. After 24 hours, a request with the token returns an HTTP 400 error: Expired 'pageToken' provided.

The token binds to the query parameters from the original request. If you change marketplaceIds, sellerId, includedData, or any filter parameter between pages, the request returns: Search parameters do not match the provided 'pageToken'.

Complete pagination within 24 hours and keep the same parameters across all pages.

📘

Tip

URL-encode the = character as %3D when you pass the token in the pageToken query parameter.