searchListingsItems

get https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/{sellerId}

Search for and return a list of selling partner listings items and their respective details.

Usage Plan:

Rate (requests per second)	Burst
5	5

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that are applied to the requested operation, when available. The preceding table contains the default rate and burst values for this operation. Selling partners whose business demands require higher throughput might have higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits.

Path Params

sellerId

string

required

A selling partner identifier, such as a merchant account or vendor code.

Query Params

marketplaceIds

array of strings

required

length ≤ 1

A comma-delimited list of Amazon marketplace identifiers for the request.

marketplaceIds*

issueLocale

string

A locale that is used to localize issues. When not provided, the default language code of the first marketplace is used. Examples: "en_US", "fr_CA", "fr_FR". When a localization is not available in the specified locale, localized messages default to "en_US".

includedData

array of strings

Defaults to summaries

A comma-delimited list of datasets that you want to include in the response. Default: summaries.

Show Details

summaries	Summary details for the listing item.
attributes	A JSON object that contains structured listing item attribute data, keyed by attribute name.
issues	Issues that are associated with the listing item.
offers	Current offers for the listing item.
fulfillmentAvailability	Fulfillment availability details for the listing item.
procurement	Vendor procurement details for the listing item.
relationships	Relationship details for a listing item (for example, variations).
productTypes	Product types associated with a listing item.

includedData

identifiers

array of strings

length ≤ 20

A comma-delimited list of product identifiers that you can use to search for listings items.

Note:

This is required when you specify identifiersType.
You cannot use 'identifiers' if you specify variationParentSku or packageHierarchySku.

identifiers

identifiersType

string

A type of product identifiers that you can use to search for listings items.

Note:
This is required when identifiers is provided.

variationParentSku

string

Filters results to include listing items that are variation children of the specified SKU.

Note: You cannot use variationParentSku if you include identifiers or packageHierarchySku in your request.

packageHierarchySku

string

Filter results to include listing items that contain or are contained by the specified SKU.

Note: You cannot use packageHierarchySku if you include identifiers or variationParentSku in your request.

createdAfter

date-time

A date-time that is used to filter listing items. The response includes listings items that were created at or after this time. Values are in ISO 8601 date-time format.

createdBefore

date-time

A date-time that is used to filter listing items. The response includes listings items that were created at or before this time. Values are in ISO 8601 date-time format.

lastUpdatedAfter

date-time

A date-time that is used to filter listing items. The response includes listings items that were last updated at or after this time. Values are in ISO 8601 date-time format.

lastUpdatedBefore

date-time

A date-time that is used to filter listing items. The response includes listings items that were last updated at or before this time. Values are in ISO 8601 date-time format.

withIssueSeverity

array of strings

Filter results to include only listing items that have issues that match one or more of the specified severity levels.

Show Details

ERROR	Indicates that an issue has occurred, which prevented the submission from processing. For example, a validation error.
WARNING	Indicates an issue has occurred that should be reviewed, but it has not prevented the submission from processing.

withIssueSeverity

withStatus

array of strings

Filter results to include only listing items that have the specified status.

Show Details

BUYABLE	The listings item can be purchased by shoppers. This status does not apply to vendor listings.
DISCOVERABLE	The listings item is visible to shoppers.

withStatus

withoutStatus

array of strings

Filter results to include only listing items that don't contain the specified statuses.

Show Details

BUYABLE	The listings item can be purchased by shoppers. This status does not apply to vendor listings.
DISCOVERABLE	The listings item is visible to shoppers.

withoutStatus

sortBy

string

Defaults to lastUpdatedDate

An attribute by which to sort the returned listing items.

sortOrder

string

Defaults to DESC

The order in which to sort the result items.

pageSize

integer

≤ 20

Defaults to 10

The number of results that you want to include on each page.

pageToken

string

A token that you can use to fetch a specific page when there are multiple pages of results.

200

Success.

Response body

object

numberOfResults

integer

required

The total number of selling partner listings items found for the search criteria (only results up to the page count limit will be returned per request regardless of the number found).

Note: The maximum number of items (SKUs) that can be returned and paged through is 1000.

pagination

object

When a request produces a response that exceeds the pageSize, pagination occurs. This means the response is divided into individual pages. To retrieve the next page or the previous page, you must pass the nextToken value or the previousToken value as the pageToken parameter in the next request. When you receive the last page, there will be no nextToken key in the pagination object.

nextToken

string

A token that can be used to fetch the next page.

previousToken

string

A token that can be used to fetch the previous page.

items

array of objects

required

A list of listings items.

items*

object

sku

string

required

A selling partner provided identifier for an Amazon listing.

summaries

array of objects

Summary details of a listings item.

summaries

object

marketplaceId

string

required

A marketplace identifier. Identifies the Amazon marketplace for the listings item.

asin

string

Amazon Standard Identification Number (ASIN) of the listings item.

productType

string

required

The Amazon product type of the listings item.

conditionType

string

Identifies the condition of the listings item.

new_new new_open_box new_oem refurbished_refurbished used_like_new used_very_good used_good used_acceptable collectible_like_new collectible_very_good collectible_good collectible_acceptable club_club

Show Details

new_new	New.
new_open_box	New - Open Box.
new_oem	New - OEM.
refurbished_refurbished	Refurbished.
used_like_new	Used - Like New.
used_very_good	Used - Very Good.
used_good	Used - Good.
used_acceptable	Used - Acceptable.
collectible_like_new	Collectible - Like New.
collectible_very_good	Collectible - Very Good.
collectible_good	Collectible - Good.
collectible_acceptable	Collectible - Acceptable.
club_club	Club.

status

array of strings

required

Statuses that apply to the listings item.

Show Details

BUYABLE	The listings item can be purchased by shoppers. This status does not apply to vendor listings.
DISCOVERABLE	The listings item is visible to shoppers.

status*

fnSku

string

The fulfillment network stock keeping unit is an identifier used by Amazon fulfillment centers to identify each unique item.

itemName

string

The name or title associated with an Amazon catalog item.

createdDate

date-time

required

The date the listings item was created in ISO 8601 format.

lastUpdatedDate

date-time

required

The date the listings item was last updated in ISO 8601 format.

mainImage

object

The image for the listings item.

attributes

object

A JSON object containing structured listings item attribute data keyed by attribute name.

Has additional fields

issues

array of objects

The issues associated with the listings item.

issues

object

code

string

required

An issue code that identifies the type of issue.

message

string

required

A message that describes the issue.

severity

string

required

The severity of the issue.

ERROR WARNING INFO

Show Details

ERROR	Indicates an issue has occurred preventing the submission from processing, such as a validation error.
WARNING	Indicates an issue has occurred that should be reviewed, but has not prevented the submission from processing.
INFO	Indicates additional information has been provided that should be reviewed.

attributeNames

array of strings

The names of the attributes associated with the issue, if applicable.

attributeNames

categories

array of strings

required

List of issue categories.

Possible vales:

INVALID_ATTRIBUTE - Indicating an invalid attribute in the listing.
MISSING_ATTRIBUTE - Highlighting a missing attribute in the listing.
INVALID_IMAGE - Signifying an invalid image in the listing.
MISSING_IMAGE - Noting the absence of an image in the listing.
INVALID_PRICE - Pertaining to issues with the listing's price-related attributes.
MISSING_PRICE - Pointing out the absence of a price attribute in the listing.
DUPLICATE - Identifying listings with potential duplicate problems, such as this ASIN potentially being a duplicate of another ASIN.
QUALIFICATION_REQUIRED - Indicating that the listing requires qualification-related approval.

categories*

enforcements

object

This field provides information about the enforcement actions taken by Amazon that affect the publishing or status of a listing. It also includes details about any associated exemptions.

offers

array of objects

Offer details for the listings item.

offers

object

marketplaceId

string

required

The Amazon marketplace identifier.

offerType

string

required

Type of offer for the listings item.

B2C B2B

Show Details

B2C	The offer on this listings item is available for Business to Consumer purchase, meaning that it is available to shoppers on Amazon retail sites.
B2B	The offer on this listings item is available for Business to Business purchase.

price

object

required

The currency type and amount.

points

object

The number of Amazon Points offered with the purchase of an item, and their monetary value. Note that the Points element is only returned in Japan (JP).

audience

object

Buyer segment or program this offer is applicable to.

fulfillmentAvailability

array of objects

The fulfillment availability for the listings item.

fulfillmentAvailability

object

fulfillmentChannelCode

string

required

The code of the fulfillment network that will be used.

quantity

integer

≥ 0

The quantity of the item you are making available for sale.

procurement

array of objects

The vendor procurement information for the listings item.

procurement

object

costPrice

object

required

The currency type and amount.

relationships

array of objects

Relationships for a listing item, by marketplace (for example, variations).

relationships

object

marketplaceId

string

required

Amazon marketplace identifier.

relationships

array of objects

required

Relationships for the listing item.

relationships*

object

childSkus

array of strings

Identifiers (SKUs) of the related items that are children of this listing item.

childSkus

parentSkus

array of strings

Identifiers (SKUs) of the related items that are parents of this listing item.

parentSkus

variationTheme

object

A variation theme that indicates the combination of listing item attributes that define the variation family.

type

string

required

The type of relationship.

VARIATION PACKAGE_HIERARCHY

Show Details

VARIATION	The listing item in the request is a variation parent or variation child of the related listing items, indicated by SKU.
PACKAGE_HIERARCHY	The listing item in the request is a package container or is contained by the related listing items, indicated by SKU.

productTypes

array of objects

Product types for a listing item, by marketplace.

productTypes

object

marketplaceId

string

required

Amazon marketplace identifier.

productType

string

required

The name of the product type that is submitted by the Selling Partner.

Headers

object

x-amzn-RateLimit-Limit

string

Your rate limit (requests per second) for this operation.

x-amzn-RequestId

string

Unique request reference identifier.

400

Request has missing or invalid parameters and cannot be parsed.

403

Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.

404

The resource specified does not exist.

413

The request size exceeded the maximum accepted size.

415

The request payload is in an unsupported format.

429

The frequency of requests was greater than allowed.

500

An unexpected condition occurred that prevented the server from fulfilling the request.

503

Temporary overloading or maintenance of the server.

xxxxxxxxxx
curl --request GET \
     --url 'https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/sellerId?includedData=summaries&sortBy=lastUpdatedDate&sortOrder=DESC&pageSize=10' \
     --header 'accept: application/json'

xxxxxxxxxx
}
{
  "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

200Success.

400Request has missing or invalid parameters and cannot be parsed.

403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.

404The resource specified does not exist.

413The request size exceeded the maximum accepted size.

415The request payload is in an unsupported format.

429The frequency of requests was greater than allowed.

500An unexpected condition occurred that prevented the server from fulfilling the request.

503Temporary overloading or maintenance of the server.