Listings Items API v2021-08-01 reference

Access data on selling partner listings on Amazon.

Selling Partner API for Listings Items

Overview

The Selling Partner API for Listings Items (Listings Items API) provides programmatic access to selling partner listings on Amazon. Use this API in collaboration with the Selling Partner API for Product Type Definitions, which you use to retrieve the information about Amazon product types needed to use the Listings Items API.

For more information, see the Listings Items API Use Case Guide.

Version information

Version : 2021-08-01

Contact information

Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html

License information

License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0

URI scheme

Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Operations

getListingsItem
putListingsItem
deleteListingsItem
patchListingsItem

Paths

GET /listings/2021-08-01/items/{sellerId}/{sku}

Operation: getListingsItem

Description

Returns details about a listings item for a selling partner.

Usage Plan:

Rate (requests per second)Burst
510

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
PathsellerId
required
A selling partner identifier, such as a merchant account or vendor code.string
Pathsku
required
A selling partner provided identifier for an Amazon listing.string
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers for the request.< string > array(csv)
QueryissueLocale
optional
A locale for localization of issues. When not provided, the default language code of the first marketplace is used. Examples: "en_US", "fr_CA", "fr_FR". Localized messages default to "en_US" when a localization is not available in the specified locale.string
QueryincludedData
optional
A comma-delimited list of data sets to include in the response. Default: summaries.< enum (IncludedData) > array(csv)

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
Item

For error status codes, descriptions and schemas, see Error responses and schemas.

Consumes

  • application/json

Produces

  • application/json

PUT /listings/2021-08-01/items/{sellerId}/{sku}

Operation: putListingsItem

Description

Creates a new or fully-updates an existing listings item for a selling partner.

Usage Plan:

Rate (requests per second)Burst
510

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
PathsellerId
required
A selling partner identifier, such as a merchant account or vendor code.string
Pathsku
required
A selling partner provided identifier for an Amazon listing.string
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers for the request.< string > array(csv)
QueryissueLocale
optional
A locale for localization of issues. When not provided, the default language code of the first marketplace is used. Examples: "en_US", "fr_CA", "fr_FR". Localized messages default to "en_US" when a localization is not available in the specified locale.string
Bodybody
required
The request body schema for the putListingsItem operation.ListingsItemPutRequest

Responses

HTTP CodeDescriptionSchema
200Successfully understood the request to create or fully-update a listings item. See the response to determine if the submission has been accepted.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
ListingsItemSubmissionResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Consumes

  • application/json

Produces

  • application/json

DELETE /listings/2021-08-01/items/{sellerId}/{sku}

Operation: deleteListingsItem

Description

Delete a listings item for a selling partner.

Usage Plan:

Rate (requests per second)Burst
510

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
PathsellerId
required
A selling partner identifier, such as a merchant account or vendor code.string
Pathsku
required
A selling partner provided identifier for an Amazon listing.string
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers for the request.< string > array(csv)
QueryissueLocale
optional
A locale for localization of issues. When not provided, the default language code of the first marketplace is used. Examples: "en_US", "fr_CA", "fr_FR". Localized messages default to "en_US" when a localization is not available in the specified locale.string

Responses

HTTP CodeDescriptionSchema
200Successfully understood the listings item delete request. See the response to determine whether the submission has been accepted.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
ListingsItemSubmissionResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Consumes

  • application/json

Produces

  • application/json

PATCH /listings/2021-08-01/items/{sellerId}/{sku}

Operation: patchListingsItem

Description

Partially update (patch) a listings item for a selling partner. Only top-level listings item attributes can be patched. Patching nested attributes is not supported.

Usage Plan:

Rate (requests per second)Burst
510

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
PathsellerId
required
A selling partner identifier, such as a merchant account or vendor code.string
Pathsku
required
A selling partner provided identifier for an Amazon listing.string
QuerymarketplaceIds
required
A comma-delimited list of Amazon marketplace identifiers for the request.< string > array(csv)
QueryissueLocale
optional
A locale for localization of issues. When not provided, the default language code of the first marketplace is used. Examples: "en_US", "fr_CA", "fr_FR". Localized messages default to "en_US" when a localization is not available in the specified locale.string
Bodybody
required
The request body schema for the patchListingsItem operation.ListingsItemPatchRequest

Responses

HTTP CodeDescriptionSchema
200Successfully understood the listings item patch request. See the response to determine if the submission was accepted.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
ListingsItemSubmissionResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Consumes

  • application/json

Produces

  • application/json

Error Responses and Schemas

This table contains HTTP status codes and associated information for error responses.

HTTP CodeDescriptionSchema
400Request has missing or invalid parameters and cannot be parsed.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
404The resource specified does not exist.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
413The request size exceeded the maximum accepted size.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
415The request payload is in an unsupported format.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
429The frequency of requests was greater than allowed.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
503Temporary overloading or maintenance of the server.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList

Definitions

Error

Error response returned when the request is unsuccessful.

NameDescriptionSchema
code
required
An error code that identifies the type of error that occurred.string
message
required
A message that describes the error condition.string
details
optional
Additional details that can help the caller understand or fix the issue.string

ErrorList

A list of error responses returned when a request is unsuccessful.

NameSchema
errors
required
< Error > array

Item

A listings item.

NameDescriptionSchema
sku
required
A selling partner provided identifier for an Amazon listing.string
summaries
optional
Summary details of a listings item.ItemSummaries
attributes
optional
JSON object containing structured listings item attribute data keyed by attribute name.ItemAttributes
issues
optional
Issues associated with the listings item.ItemIssues
offers
optional
Offer details for the listings item.ItemOffers
fulfillmentAvailability
optional
Fulfillment availability for the listings item.< FulfillmentAvailability > array
procurement
optional
Vendor procurement information for the listings item.ItemProcurement

ItemSummaries

Summary details of a listings item.

Type : < ItemSummaryByMarketplace > array

ItemSummaryByMarketplace

Summary details of a listings item for an Amazon marketplace.

NameDescriptionSchema
marketplaceId
required
A marketplace identifier. Identifies the Amazon marketplace for the listings item.string
asin
required
Amazon Standard Identification Number (ASIN) of the listings item.string
productType
required
The Amazon product type of the listings item.string
conditionType
optional
Identifies the condition of the listings item.enum (ConditionType)
status
required
Statuses that apply to the listings item.< enum (Status) > array
fnSku
optional
Fulfillment network stock keeping unit is an identifier used by Amazon fulfillment centers to identify each unique item.string
itemName
required
Name, or title, associated with an Amazon catalog item.string
createdDate
required
Date the listings item was created, in ISO 8601 format.string (date-time)
lastUpdatedDate
required
Date the listings item was last updated, in ISO 8601 format.string (date-time)
mainImage
optional
Main image for the listings item.ItemImage

ItemImage

Image for the listings item.

NameDescriptionSchema
link
required
Link, or URL, for the image.string
height
required
Height of the image in pixels.integer
width
required
Width of the image in pixels.integer

ItemAttributes

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

Type : object

ItemIssues

Issues associated with the listings item.

Type : < Issue > array

Issue

An issue with a listings item.

NameDescriptionSchema
code
required
An issue code that identifies the type of issue.string
message
required
A message that describes the issue.string
severity
required
The severity of the issue.enum (Severity)
attributeNames
optional
Names of the attributes associated with the issue, if applicable.< string > array

ItemOffers

Offer details for the listings item.

Type : < ItemOfferByMarketplace > array

ItemOfferByMarketplace

Offer details of a listings item for an Amazon marketplace.

NameDescriptionSchema
marketplaceId
required
Amazon marketplace identifier.string
offerType
required
Type of offer for the listings item.enum (OfferType)
price
required
Purchase price of the listings itemMoney
points
optional
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).Points

ItemProcurement

Vendor procurement information for the listings item.

NameDescriptionSchema
costPrice
required
The price (numeric value) that you want Amazon to pay you for this product.Money

FulfillmentAvailability

Fulfillment availability details for the listings item.

NameDescriptionSchema
fulfillmentChannelCode
required
Designates which fulfillment network will be used.string
quantity
optional
The quantity of the item you are making available for sale.
Minimum value : 0
integer

Money

The currency type and the amount.

NameDescriptionSchema
currencyCode
required
Three-digit currency code. In ISO 4217 format.string
amount
required
The currency amount.Decimal

Decimal

A decimal number with no loss of precision. Useful when precision loss is unnaceptable, as with currencies. Follows RFC7159 for number representation.

Type : string

Points

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

NameSchema
pointsNumber
required
integer

PatchOperation

Individual JSON Patch operation for an HTTP PATCH request.

NameDescriptionSchema
op
required
Type of JSON Patch operation. Supported JSON Patch operations include add, replace, and delete. See https://tools.ietf.org/html/rfc6902.enum (Op)
path
required
JSON Pointer path of the element to patch. See https://tools.ietf.org/html/rfc6902.string
value
optional
JSON value to add, replace, or delete.< object > array

ListingsItemPatchRequest

The request body schema for the patchListingsItem operation.

NameDescriptionSchema
productType
required
The Amazon product type of the listings item.string
patches
required
One or more JSON Patch operations to perform on the listings item.< PatchOperation > array

ListingsItemPutRequest

The request body schema for the putListingsItem operation.

NameDescriptionSchema
productType
required
The Amazon product type of the listings item.string
requirements
optional
The name of the requirements set for the provided data.enum (Requirements)
attributes
required
JSON object containing structured listings item attribute data keyed by attribute name.object

ListingsItemSubmissionResponse

Response containing the results of a submission to the Selling Partner API for Listings Items.

NameDescriptionSchema
sku
required
A selling partner provided identifier for an Amazon listing.string
status
required
The status of the listings item submission.enum (Status)
submissionId
required
The unique identifier of the listings item submission.string
issues
optional
Listings item issues related to the listings item submission.< Issue > array

IncludedData

Type : enum

ValueDescription
summariesSummary details of the listing item.
attributesJSON object containing structured listing item attribute data keyed by attribute name.
issuesIssues associated with the listing item.
offersCurrent offers for the listing item.
fulfillmentAvailabilityFulfillment availability details for the listing item.
procurementVendor procurement details for the listing item.

Op

Type of JSON Patch operation. Supported JSON Patch operations include add, replace, and delete. See https://tools.ietf.org/html/rfc6902.

Type : enum

ValueDescription
addThe "add" operation adds or replaces the target property.
replaceThe "replace" operation adds or replaces the target property.
deleteThe "delete" operation removes the target property.

Severity

The severity of the issue.

Type : enum

ValueDescription
ERRORIndicates an issue has occurred preventing the submission from processing, such as a validation error.
WARNINGIndicates an issue has occurred that should be reviewed, but has not prevented the submission from processing.
INFOIndicates additional information has been provided that should be reviewed.

ConditionType

Identifies the condition of the listings item.

Type : enum

ValueDescription
new_newNew
new_open_boxNew - Open Box.
new_oemNew - OEM.
refurbished_refurbishedRefurbished
used_like_newUsed - Like New.
used_very_goodUsed - Very Good.
used_goodUsed - Good.
used_acceptableUsed - Acceptable.
collectible_like_newCollectible - Like New.
collectible_very_goodCollectible - Very Good.
collectible_goodCollectible - Good.
collectible_acceptableCollectible - Acceptable.
club_clubClub

Requirements

The name of the requirements set for the provided data.

Type : enum

ValueDescription
LISTINGIndicates the submitted data contains product facts and sales terms.
LISTING_PRODUCT_ONLYIndicates the submitted data contains product facts only.
LISTING_OFFER_ONLYIndicates the submitted data contains sales terms only.

OfferType

Type of offer for the listings item.

Type : enum

ValueDescription
B2CThe offer on this listings item is available for Business to Consumer purchase, meaning that it is available to shoppers on Amazon retail sites.
B2BThe offer on this listings item is available for Business to Business purchase.

Status

Type : enum

For use with the definition(s): ItemSummaryByMarketplace

ValueDescription
BUYABLEThe listings item can be purchased by shoppers. This status does not apply to vendor listings.
DISCOVERABLEThe listings item is visible to shoppers.

For use with the definition(s): ListingsItemSubmissionResponse
The status of the listings item submission.

ValueDescription
ACCEPTEDThe listings submission was accepted for processing.
INVALIDThe listings submission was not valid and was not accepted for processing.