Listings Items API v2020-09-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 Listing Items API Use Case Guide (opens new window).

# Version information

Version : 2020-09-01

# Operations

putListingsItem
deleteListingsItem
patchListingsItem

# Paths

# putListingsItem

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

# Description

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

Usage Plans:

Plan type Rate (requests per second) Burst
Default 5 10
Selling partner specific Variable Variable

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 (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/2020-09-01/items/{sellerId}/{sku}

# Description

Delete a listings item for a selling partner.

Usage Plans:

Plan type Rate (requests per second) Burst
Default 5 10
Selling partner specific Variable Variable

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 (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/2020-09-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 Plans:

Plan type Rate (requests per second) Burst
Default 5 10
Selling partner specific Variable Variable

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 (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
413 The 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
415 The 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
429 The 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
500 An 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
503 Temporary 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.

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

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

# Status

The status of the listings item submission.

Type : enum

Value Description
ACCEPTED The listings submission was accepted for processing.
INVALID The 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 (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.

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