Listings Items API v2021-08-01 reference

AmazonSPAPI

# 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 (opens new window).

# Version information

Version : 2021-08-01

# Operations

getListingsItem
putListingsItem
deleteListingsItem
patchListingsItem

# Paths

# getListingsItem

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

# Description

Returns details about a listings item for a selling partner.

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API (opens new window).

# 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
Query includedData
optional
A comma-delimited list of data sets to include in the response. Default: summaries. < enum (IncludedData) > array(csv)

# 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

# putListingsItem

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

# Description

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

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API (opens new window).

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

# deleteListingsItem

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

# Description

Delete a listings item for a selling partner.

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 (opens new window).

# 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

# patchListingsItem

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

# 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
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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API (opens new window).

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

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

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

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

Name Description Schema
marketplaceId
required
Amazon marketplace identifier. string
offerType
required
Type of offer for the listings item. enum (OfferType)
price
required
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

# ItemProcurement

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

Fulfillment availability details for the listings item.

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

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

# 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. See https://tools.ietf.org/html/rfc6902 (opens new window). enum (Op)
path
required
JSON Pointer path of the element to patch. See https://tools.ietf.org/html/rfc6902 (opens new window). 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
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

# IncludedData

Type : enum

Value Description
summaries Summary details of the listing item.
attributes JSON object containing structured listing item attribute data keyed by attribute name.
issues Issues 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.

# Op

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

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

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

# Status

Type : enum

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): 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.
Last Updated: 10/11/2022, 9:45:34 PM