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(`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. 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`	Refer to the 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"
            }
          ]
        }
      ]
    }
  ]
}

Updated 3 months ago