API Version: 2021-08-01
- What is the Listings Restrictions API?
- Tutorial: Get listings restrictions for an item in the catalog
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 may be able take additional steps to request approval to create a listing. See 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. See 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 Stock Keeping Unit (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 may be available to apply for approval.
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. See the Selling Partner API Developer Guide 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. See the Selling Partner API Developer Guide for more information.
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(ConditionType) |
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. See the Selling Partner API Developer Guide 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 may include a variety of approval requirements and qualifications. If the reasonCode in the response indicates that approval is required, the selling partner may 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: < Restriction > array |
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"
}
]
}
]
}
]
}