Listings Items API v2021-08-01 Reference

Access selling partner listings data on Amazon.

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.

Note: The parameters associated with this operation may contain special characters that must be encoded to successfully call the API. To avoid errors with SKUs when encoding URLs, refer to URL Encoding.

Usage Plan:

Rate (requests per second)	Burst
5	10

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 than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

Type	Name	Description	Schema	Default
Path	sellerId required	A selling partner identifier, such as a merchant account or vendor code.	string	-
Path	sku required	A selling partner provided identifier for an Amazon listing.	string	-
Query	marketplaceIds required	A comma-delimited list of Amazon marketplace identifiers for the request.	< string > array(csv)	-
Query	issueLocale 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	-
Query	includedData optional	A comma-delimited list of data sets to include in the response. Default: `summaries`.	< enum (IncludedData) > array(csv)	`summaries`

Responses

HTTP Code	Description	Schema
200	Success. 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 or fully updates an existing listings item for a selling partner.

Note: This operation has a throttling rate of one request per second when mode is VALIDATION_PREVIEW.

Usage Plan:

Rate (requests per second)	Burst
5	10

Parameters

Type	Name	Description	Schema	Default
Path	sellerId required	A selling partner identifier, such as a merchant account or vendor code.	string	-
Path	sku required	A selling partner provided identifier for an Amazon listing.	string	-
Query	marketplaceIds required	A comma-delimited list of Amazon marketplace identifiers for the request.	< string > array(csv)	-
Query	includedData optional	A comma-delimited list of data sets to include in the response. Default: `issues`.	< enum (IncludedData) > array(csv)	`issues`
Query	mode optional	The mode of operation for the request.	enum (Mode)	-
Query	issueLocale 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	-
Body	body required	The request body schema for the `putListingsItem` operation.	ListingsItemPutRequest	-

Responses

HTTP Code	Description	Schema
200	Successfully 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
5	10

Parameters

Type	Name	Description	Schema
Path	sellerId required	A selling partner identifier, such as a merchant account or vendor code.	string
Path	sku required	A selling partner provided identifier for an Amazon listing.	string
Query	marketplaceIds required	A comma-delimited list of Amazon marketplace identifiers for the request.	< string > array(csv)
Query	issueLocale 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 Code	Description	Schema
200	Successfully 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.

Note: This operation has a throttling rate of one request per second when mode is VALIDATION_PREVIEW.

Usage Plan:

Rate (requests per second)	Burst
5	10

Parameters

Type	Name	Description	Schema	Default
Path	sellerId required	A selling partner identifier, such as a merchant account or vendor code.	string	-
Path	sku required	A selling partner provided identifier for an Amazon listing.	string	-
Query	marketplaceIds required	A comma-delimited list of Amazon marketplace identifiers for the request.	< string > array(csv)	-
Query	includedData optional	A comma-delimited list of data sets to include in the response. Default: `issues`.	< enum (IncludedData) > array(csv)	`issues`
Query	mode optional	The mode of operation for the request.	enum (Mode)	-
Query	issueLocale 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	-
Body	body required	The request body schema for the `patchListingsItem` operation.	ListingsItemPatchRequest	-

Responses

HTTP Code	Description	Schema
200	Successfully 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 Code	Description	Schema
400	Request 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
403	Indicates 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
404	The 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
413	The request size exceeded the maximum accepted size. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
415	The request payload is in an unsupported format. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
429	The frequency of requests was greater than allowed. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
500	An unexpected condition occurred that prevented the server from fulfilling the request. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
503	Temporary 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.

Name	Description	Schema
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.

Name	Schema
errors required	< Error > array

Item

A listings item.

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

ItemSummaries

Summary details of a listings item.

Type : < ItemSummaryByMarketplace > array

ItemSummaryByMarketplace

Summary details of a listings item for an Amazon marketplace.

Name	Description	Schema
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	The fulfillment network stock keeping unit is an identifier used by Amazon fulfillment centers to identify each unique item.	string
itemName required	The name or title associated with an Amazon catalog item.	string
createdDate required	The date the listings item was created in ISO 8601 format.	string (date-time)
lastUpdatedDate required	The date the listings item was last updated in ISO 8601 format.	string (date-time)
mainImage optional	The main image for the listings item.	ItemImage

ItemImage

The image for the listings item.

Name	Description	Schema
link required	The link, or URL, to the image.	string
height required	The height of the image in pixels.	integer
width required	The width of the image in pixels.	integer

ItemAttributes

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

Type : object

ItemIssues

The issues associated with the listings item.

Type : < Issue > array

Issue

An issue with a listings item.

Name	Description	Schema
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	The names of the attributes associated with the issue, if applicable.	< string > array
categories 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. Example : `[ "INVALID_ATTRIBUTE" ]`	< string > array
enforcements optional	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.	IssueEnforcements

IssueEnforcements

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.

Name	Description	Schema
actions required	List of enforcement actions taken by Amazon that affect the publishing or status of a listing.	< IssueEnforcementAction > array
exemption required	The "exemption" field serves to convey the status of enforcement actions by Amazon.	IssueExemption

IssueEnforcementAction

The enforcement action taken by Amazon that affect the publishing or status of a listing

Name	Description	Schema
action required	The enforcement action name. Possible values: `LISTING_SUPPRESSED` - This enforcement takes down the current listing item's buyability. `ATTRIBUTE_SUPPRESSED` - An attribute's value on the listing item is invalid, which causes it to be rejected by Amazon. `CATALOG_ITEM_REMOVED` - This catalog item is inactive on Amazon, and all offers against it in the applicable marketplace are non-buyable. `SEARCH_SUPPRESSED` - This value indicates that the catalog item is hidden from search results. Example : `"LISTING_SUPPRESSED"`	string

IssueExemption

Conveying the status of the listed enforcement actions and, if applicable, provides information about the exemption's expiry date.

Name	Description	Schema
status required	This field indicates the current exemption status for the listed enforcement actions. It can take values such as `EXEMPT`, signifying permanent exemption, `EXEMPT_UNTIL_EXPIRY_DATE` indicating temporary exemption until a specified date, or `NOT_EXEMPT` signifying no exemptions, and enforcement actions were already applied.	enum (Status)
expiryDate optional	This field represents the timestamp, following the ISO 8601 format, which specifies the date when temporary exemptions, if applicable, will expire, and Amazon will begin enforcing the listed actions. Example : `"2023-10-28T00:36:48.914Z"`	string (date-time)

ItemOffers

Offer details for the listings item.

Type : < ItemOfferByMarketplace > array

ItemOfferByMarketplace

Offer details of a listings item for an Amazon marketplace.

Name	Description	Schema
marketplaceId required	The Amazon marketplace identifier.	string
offerType required	Type of offer for the listings item.	enum (OfferType)
price required	The purchase price of the listings item	Money
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
audience optional	Buyer segment or program this offer is applicable to.	Audience

ItemProcurement

The vendor procurement information for the listings item.

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

FulfillmentAvailability

The fulfillment availability details for the listings item.

Name	Description	Schema
fulfillmentChannelCode required	The code of the fulfillment network that 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 amount.

Name	Description	Schema
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).

Name	Schema
pointsNumber required	integer

Audience

Buyer segment or program this offer is applicable to.

Name	Description	Schema
value optional	Name of the audience an offer is applicable to. Common values: 'ALL' - Standard offer audience for buyers on Amazon retail websites. 'B2B' - Offer audience for Amazon Business website buyers. Example : `"ALL"`	string
displayName optional	Localized display name for the audience.	string

PatchOperation

Individual JSON Patch operation for an HTTP PATCH request.

Name	Description	Schema
op required	Type of JSON Patch operation. Supported JSON Patch operations include add, replace, and delete. Refer to JavaScript Object Notation (JSON) Patch for more information.	enum (Op)
path required	JSON Pointer path of the element to patch. Refer to JavaScript Object Notation (JSON) Patch for more information.	string
value optional	JSON value to add, replace, or delete.	< object > array

ListingsItemPatchRequest

The request body schema for the patchListingsItem operation.

Name	Description	Schema
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.

Name	Description	Schema
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	A 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.

Name	Description	Schema
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
identifiers optional	Identity attributes associated with the item in the Amazon catalog, such as the ASIN.	ItemIdentifiers

ItemIdentifiers

Identity attributes associated with the item in the Amazon catalog, such as the ASIN.

Type : < ItemIdentifiersByMarketplace > array

ItemIdentifiersByMarketplace

Identity attributes associated with the item in the Amazon catalog for the indicated Amazon marketplace.

Name	Description	Schema
marketplaceId optional	A marketplace identifier. Identifies the Amazon marketplace for the listings item.	string
asin optional	Amazon Standard Identification Number (ASIN) of the listings item.	string

Op

Type of JSON Patch operation. Supported JSON Patch operations include add, replace, and delete. Refer to JavaScript Object Notation (JSON) Patch for more information.

Type : enum

Value	Description
add	The `add` operation adds or replaces the target property.
replace	The `replace` operation adds or replaces the target property.
delete	The `delete` operation removes the target property. Not supported for vendors (vendors will receive an HTTP status code 400 response).

Mode

The mode of operation for the request.

Type : enum

Value	Description
VALIDATION_PREVIEW	Indicates the submitted data should be validated using the values provided in the payload and validation errors the selling partner account may face. This will synchronously perform the same checks that are preformed on submissions after being accepted for processing, but without persisting to the selling partner's catalog.

Severity

The severity of the issue.

Type : enum

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

ConditionType

Identifies the condition of the listings item.

Type : enum

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

Requirements

The name of the requirements set for the provided data.

Type : enum

Value	Description
LISTING	Indicates the submitted data contains product facts and sales terms.
LISTING_PRODUCT_ONLY	Indicates the submitted data contains product facts only.
LISTING_OFFER_ONLY	Indicates the submitted data contains sales terms only. Not supported for vendors (vendors will receive an HTTP status code 400 response).

OfferType

Type of offer for the listings item.

Type : enum

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

IncludedData

Type : enum

For use with the operation(s): getListingsItem

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.

For use with the operation(s): putListingsItem, patchListingsItem

Value	Description
identifiers	Identifiers associated with the item in the Amazon catalog, such as Amazon Standard Identification Number (ASIN). Can only be requested when `mode` is `VALIDATION_PREVIEW`.
issues	The issues associated with the listing item.

Status

Type : enum

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

Value	Description
ACCEPTED	The listings submission was accepted for processing.
INVALID	The listings submission was not valid and was not accepted for processing.
VALID	The listings submission was valid. Only returned when the `mode` is `VALIDATION_PREVIEW`.

For use with the definition(s): ItemSummaryByMarketplace

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

For use with the definition(s): IssueExemption
This field indicates the current exemption status for the listed enforcement actions. It can take values such as EXEMPT, signifying permanent exemption, EXEMPT_UNTIL_EXPIRY_DATE indicating temporary exemption until a specified date, or NOT_EXEMPT signifying no exemptions, and enforcement actions were already applied.

Value	Description
EXEMPT	This status is assigned to a product listing when it has been exempted from the listed enforcement actions. In cases of `EXEMPT`, Amazon acknowledges the existence of enforcement actions but ensures the user that these actions will not be applied to the listing. The user is advised to consider addressing the issue, although enforcement actions will not be taken.
EXEMPT_UNTIL_EXPIRY_DATE	This status indicates that a product listing has been granted a temporary exemption from the listed enforcement actions. The exemption will remain in effect until a specified expiry date. After this date, Amazon will enforce the listed actions. The `expiryDate` field provides the timestamp indicating when the temporary exemption will end, adhering to the ISO 8601 format
NOT_EXEMPT	This status is assigned to a product listing when it has no exemptions from the listed enforcement actions. When the status is `NOT_EXEMPT`, it signifies that Amazon has already taken the specified enforcement actions. There is no exemption in place, and the listed actions are actively enforced

Updated about 2 months ago