Amazon Selling Partner API - spapi.cyou

Listings Restrictions API v2021-08-01 Use Case Guide

AmazonSPAPI

# 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 may be able take additional steps to request approval to create a listing. See the Listings Restrictions API Reference (opens new window) 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 (opens new window) 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.

# 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:

# Step 1 - Get listings restrictions for an item in the Amazon catalog

Call the getListingsRestrictions (opens new window) 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
1
2
3
4
5

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 (opens new window) 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": [
    {
    }
  ]
}
1
2
3
4
5
6

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"
            }
          ]
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186

Notifications API v1