Listings Items API v2020-09-01 reference

Access data on selling partner listings on Amazon.

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 Listing Items API Use Case Guide.

Version information

Version : 2020-09-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

putListingsItem
deleteListingsItem
patchListingsItem

Paths

PUT /listings/2020-09-01/items/{sellerId}/{sku}

Operation: putListingsItem

Description

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

Usage Plans:

Plan typeRate (requests per second)Burst
Default510
Selling partner specificVariableVariable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. 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/2020-09-01/items/{sellerId}/{sku}

Operation: deleteListingsItem

Description

Delete a listings item for a selling partner.

Usage Plans:

Plan typeRate (requests per second)Burst
Default510
Selling partner specificVariableVariable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. 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/2020-09-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 Plans:

Plan typeRate (requests per second)Burst
Default510
Selling partner specificVariableVariable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. 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
413The request size exceeded the maximum accepted size.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
415The request payload is in an unsupported format.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
429The frequency of requests was greater than allowed.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
503Temporary overloading or maintenance of the server.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
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

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)
attributeName
optional
Name of the attribute associated with the issue, if applicable.string

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

Status

The status of the listings item submission.

Type : enum

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

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.

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.