Listings Restrictions API v2021-08-01 Use Case Guide
How to programmatically identify restrictions on Amazon catalog listings.
API Version: 2021-08-01
What is the Listings Restrictions API?
Using the Selling Partner API for Listings Restrictions (Listings Restrictions API), you can check whether restrictions exist that prevent the creation of a listing for an item in the Amazon catalog. If an item is restricted, you might be able take additional steps to request approval to create a listing. Refer to the Listings Restrictions API Reference for details about API operations and associated data types and schemas.
Use the Listings Restrictions API in conjunction with the Listings Items API. For example, you can first determine whether listings restrictions exist using the Listings Restrictions API. If no restrictions exist, you can then call the Listings Items API to create offer-only listings. Refer to the Listings Items API Reference for more information about the Listings Items API.
Key Features
- The Listings Restrictions API provides details about listings restrictions, if any, on an existing catalog item identified by ASIN.
- You can optionally filter the restrictions based on condition type.
- The Listings Restrictions API supports checking multiple marketplaces for listings restrictions in a single call.
- When approval is required, the Listings Restrictions API returns next step links so you can pursue approval to create the listing.
Terminology
-
ASIN: Amazon Standard Identification Number that identifies an item in the Amazon catalog.
-
Listing: An Amazon listing is an item that a selling partner has listed for sale on Amazon and is identified by a SKU. Product facts included in Amazon listings are reconciled into Amazon catalog items, which are identified by Amazon Standard Identification Numbers (ASINs)
-
Restriction: A restriction is a condition that prevents the creation of a listing. In some instances, the restriction is due to an approval requirement, in which case additional steps might be available to apply for approval.
Tutorial: Get listings restrictions for an item in the catalog
Use this tutorial to retrieve any listings restrictions for an existing item in the Amazon catalog.
Prerequisites
To complete this tutorial, you will need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
- The Product Listing role assigned to your developer profile.
- The Product Listing role selected in the App registration page for your application.
- A basic understanding of the Selling Partner API. Refer to What is the Selling Partner API? for more information.
Step 1: Get listings restrictions for an item in the Amazon catalog
Call the getListingsRestrictions
operation to return any listings restrictions, passing the following parameters:
Query Parameters
Parameter | Example | Description | Required |
---|---|---|---|
asin |
B0000ASIN1 |
The Amazon Standard Identification Number (ASIN) of the item. Type: string |
Yes |
conditionType |
used_very_good |
The condition used to filter restrictions. Type: enum( |
No |
sellerid |
AXXXXXXXXXXX |
A selling partner identifier, such as a merchant account. Type: string |
Yes |
marketplaceIds |
ATVPDKIKX0DER |
Comma-delimited list of Amazon marketplace identifiers for the request. Refer to Marketplace IDs for the list of Amazon marketplace identifiers. Type: < string > array(csv) |
Yes |
reasonLocale |
en_US |
A locale for reason text localization. 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.Type: string |
No |
Example Request
https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/restrictions
?asin=B08XXLG119
&conditionType=
&sellerId=AXXXXXXXXXXX
&marketplaceIds=ATVPDKIKX0DER
Response
A successful response returns information about all of the applicable restrictions, if any. If there are no restrictions for the specified conditionType (when provided) in the specified marketplace, the list of restrictions in the response will be empty.
When restrictions do exist for the specified conditionType
(when provided) in the specified marketplace, evaluate the reasons
array in the response to determine the reason and to identify next steps, if any. Each reason has a reasonCode
indicating why the listing is restricted.
When approval is required
Amazon requires that selling partners obtain approval before listing certain items for sale. The approval process can include a variety of approval requirements and qualifications. If the reasonCode
in the response indicates that approval is required, the selling partner might be able to apply for approval to list the item.
In this case, use the information in the links array in the response to instruct the selling partner to navigate to the URL link provided, and then to follow the instructions there to apply for approval to list.
A successful response includes the following:
Name | Example | Description |
---|---|---|
restrictions |
See Example Response | A list of restrictions for the specified Amazon catalog item. Type: < |
Example Response (no restrictions)
{
"restrictions": [
{
}
]
}
Example Response (restrictions exist)
{
"restrictions": [
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "collectible_like_new",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "new_new",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You need approval to list.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "used_acceptable",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "used_like_new",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "collectible_very_good",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "used_very_good",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "collectible_acceptable",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "collectible_good",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "used_good",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
},
{
"marketplaceId": "ATVPDKIKX0DER",
"conditionType": "refurbished_refurbished",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "You cannot list the product in this condition.",
"links": [
{
"resource": "https://sellercentral.amazon.com/hz/approvalrequest/restrictions/approve?asin=B08XXLG119",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
}
]
}
Updated 1 day ago