Amazon Selling Partner API - spapi.cyou

Listings Items API v2021-08-01 Use Case Guide

AmazonSPAPI

# What is the Listings Items API?

Using the Selling Partner API for Listings Items (Listings Items API), you can create, edit, delete, and retrieve details about Amazon listings (SKUs) for a selling partner. This includes product facts, such as item titles, and sales terms, such as price and inventory. See the Listings Items API Reference (opens new window) for details about Listings Items API operations and associated data types and schemas.

Listings data submitted to the Listings Items API adheres to the JSON Schema format provided by the Selling Partner API for Product Type Definitions (opens new window). See the Product Type Definitions API documentation for details on retrieving schemas for supported Amazon product types and validating data prior to submitting to Amazon with the Listings Items API.

Key Features

  • Retrieve Details about Listings: The Listings Items API accepts GET operations to return detailed information about an existing listing.

  • Create or Fully Update Listings: The Listings Items API accepts PUT operations to create a new listing or fully replace the data for an existing listing.

  • Partially Update Listings: The Listings Items API accepts PATCH operations to update one or more individual attributes for an existing listing, such as for updating price and quantity. Additionally, the Listings Items API accepts PATCH operations to delete one or more individual attributes for an existing listing.

  • Delete Listings: The Listings Items API accepts DELETE operations to delete an existing listing.

  • Localized Issue Messages: The Listings Items API provides localized issue messaging either in the locale specified by the calling application or the default locale of the Amazon marketplace.

  • Submission Validation: The Listings Items API provides validation of submission data prior to accepting a submission for processing. Validation errors that prevent further processing are provided synchronously to the calling application.

Terminology

  • 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).

  • Full Update: A full update to an Amazon listing results in full data requirements validation on the submitted data and either creates a new listing or replaces the data for an existing listing.

  • Partial Update: A partial update to an Amazon listing results in partial data requirements validation for the attributes provided and updates one or more attributes for an existing listing.

  • Product Type: An Amazon product type is a hierarchal categorization of items in the Amazon catalog. Item data requirements are tied to the associated product type of the item.

Considerations

  • 1x1 Updates: The Listings Items API accepts listings updates one at a time. For use-cases better suited to bulk uploads, the JSON_LISTINGS_FEED feed type may be used with the Selling Partner API for Feeds. The JSON_LISTINGS_FEED is the bulk equivalent of the Listings Items API, offering the same features and schemas provided by the Selling Partner API for Product Type Definitions.

  • Fully Supported Product Types: The Listings Items API does not yet fully support all Amazon product types. Supported Amazon product types differ by selling partner type (merchant or vendor) and by Amazon marketplace. Refer to the Selling Partner API for Product Type Definitions for the latest available Amazon product types.

  • Partially Supported Product Types: For Amazon product types not yet fully supported by the Listings Items API, offer-only submissions for existing ASINs and partial updates are supported by using the PRODUCT product type.

  • Results and Issues: Responses from the Listings Items putListingsItem, patchListingsItem and deleteListingsItem operations indicate whether or not the submission was accepted for processing, along with any issues preventing the submission from being accepted. Responses do not include issues that occur after accepting the submission for processing. Responses to the Listings Items getListingsItem operation can include issues that occur after the submission has been processed.

# Tutorial: Retrieve details about a listing

Use this tutorial to return detailed information about an Amazon listing for a given selling partner and Amazon marketplace. The details returned can include a number of optional data sets that provide important information about the state of the listing.

Important: The new LISTINGS_ITEM_ISSUES_CHANGE and LISTINGS_ITEM_STATUS_CHANGE notifications mentioned in the following paragraphs are available only to sellers at this time.

For example, if you have subscribed to receive the LISTINGS_ITEM_ISSUES_CHANGE notification using the Selling Partner API for Notifications (opens new window) (Notifications API) and you receive the notification, you can call the getListingsItem operation of the Listings Item API to get more details. The LISTINGS_ITEM_ISSUES_CHANGE notification does not include the same level of detailed information about issues as does the API. To return more detailed information, call getListingsItem and specify issues in the includedData parameter to get the issues data set.

Similarly, if you subscribe to the LISTINGS_ITEM_STATUS_CHANGE notification using the Notifications API and you receive the notification, you can call the getListingsItem operation to receive more detailed info. For example, if a listing ceases to be DISCOVERABLE as indicated in the notification, you may want to get the issues data set to see the reason for the search suppression.

For another example, if the LISTINGS_ITEM_STATUS_CHANGE notification does not indicate that the listing is buyable (i.e. Status does not include BUYABLE), a common reason could be a lack of inventory. In that case, call the getListingsItem operation and include fulfillmentAvailability in the includedData parameter to return the fulfillmentAvailability data set.

In general, the data sets available via the includedData parameter will help you better understand the status of the listing. The data sets available include summary information, contributed attributes, issues, offer information (sellers), fulfillment availability (sellers), and procurement details (vendors).

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 (opens new window) for more information.

  • Approval for the Product Listing role in your developer profile.

  • The Product Listing role selected in the App registration page for your application.

# Step 1: Submit listings item get request

Call the getListingsItem (opens new window) operation to return details about a listings item, passing the following parameters:

Request Parameters

Path Parameters

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX A selling partner identifier, such as a merchant account or vendor code.

Type: string

 Yes
sku ABC123 Identifier (stock keeping unit) of the listings item that is unique to the selling partner.

Type: string

 Yes

Query Parameters

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

See the Selling Partner API Developer Guide for the list of Amazon marketplace identifiers.

Type: < string > array(csv)

 Yes
issueLocale en_US Locale for issue localization.

Default: When no locale is provided, the default locale of the first marketplace is used. Localization defaults to en_US when a localized message is not available in the specified locale.

Type: string

 No
includedData summaries A comma-delimited list of data sets to include in the response. See IncludedData in the API reference for the list of available data sets.

Default: summaries.

Type: < enum (IncludedData) > array(csv)

 No

Example Request

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/50-TS3D-QEPT
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &includedData=issues,attributes,summaries,offers,fulfillmentAvailability
1
2
3
4

Response

A successful response includes one or more of the following:

Name Example Description
sku ABC123 Identifier (stock keeping unit) of the listings item that is unique to the selling partner.

Type: string

summaries See Example Response Summary details of a listings item.

Type: ItemSummaries

attributes See Example Response JSON object containing structured listings item attribute data keyed by attribute name.

Type: ItemAttributes

issues See Example Response Issues associated with the listings item.

Type: ItemIssues

offers See Example Response Offer details for the listings item.

Type: ItemOffers

fulfillmentAvailability See Example Response Fulfillment availability for the listings item.

Type: < FulfillmentAvailability > array

procurement See Example Response Vendor procurement information for the listings item.

Type: ItemProcurement

Example Response

Example response for a seller (merchant) that includes the summaries, attributes, issues, offers, and fulfillmentAvailability data sets.

{
  "sku": "50-TS3D-QEPT",
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B08YRD1CNN",
      "productType": "DRINKING_CUP",
      "conditionType": "new_new",
      "status": [
        "BUYABLE",
        "DISCOVERABLE"
      ],
      "itemName": "6 Pack Coffee Mug Set, Farielyn-X 16 Ounce Ceramic Coffee Cups, Black Large Coffee mugs, Restaurant Coffee Cups for Coffee, Tea, Cappuccino, Cocoa, Cereal, Matte Black Outside and Colorful Inside",
      "createdDate": "2021-07-14T19:57:02.327Z",
      "lastUpdatedDate": "2021-07-14T19:57:10.637Z",
      "mainImage":
      {
        "link": "https://m.media-amazon.com/images/I/41epVg7mZoS.jpg",
        "height": 500,
        "width": 500
      }
    }
  ],
  "attributes":
  {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_shipping_group": [
      {
        "value": "legacy-template-id",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "B08YRD1CNN",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "purchasable_offer": [
      {
        "currency": "USD",
        "start_at":
        {
          "value": "2021-07-14T19:56:57.717Z"
        },
        "our_price": [
          {
            "schedule": [
              {
                "value_with_tax": 30.0
              }
            ]
          }
        ],
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "fulfillment_availability": [
      {
        "fulfillment_channel_code": "DEFAULT",
        "quantity": 1,
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "main_product_image_locator": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxx1.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "other_product_image_locator_1": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx2.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "other_product_image_locator_2": [
      {
        "media_location": "https://media-origin-na-ssl.integ.amazon.com/images/I/xxxxx3.jpg",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ]
  },
  "issues": [
    {
      "message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): item_weight, theme, item_dimensions, item_diameter",
      "severity": "WARNING",
      "attributeName": "item_diameter",
      "attributeNames": [
        "item_diameter",
        "item_dimensions",
        "item_weight",
        "theme"
      ]
    },
    {
      "message": "Attributes tagged as customer_returns are incomplete. Provide values for the following attribute(s): color, item_dimensions, item_weight",
      "severity": "WARNING",
      "attributeName": "color",
      "attributeNames": [
        "color",
        "item_dimensions",
        "item_weight"
      ]
    }
  ],
  "offers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "offerType": "B2C",
      "price":
      {
        "currency": "USD",
        "amount": "30.0"
      }
    }
  ],
  "fulfillmentAvailability": [
    {
      "fulfillmentChannelCode": "DEFAULT",
      "quantity": 1
    }
  ]
}
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

Example request and response for a vendor that includes summaries, procurement, and issues data sets.

Example Request

GET https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXX/example-sku
  ?marketplaceIds=ATVPDKIKX0DER
  &issueLocale=en_US
  &includedData=summaries,procurement,issues
1
2
3
4

Example Response

{
  "sku": "example-sku",
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B071VG5N9D",
      "productType": "LUGGAGE",
      "conditionType": "new_new",
      "status": [
        "DISCOVERABLE"
      ],
      "itemName": "Hardside Carry-On Spinner Suitcase Luggage",
      "createdDate": "2021-02-01T00:00:00Z",
      "lastUpdatedDate": "2021-03-01T00:00:00Z",
      "mainImage":
      {
        "link": "https://www.example.com/luggage.png",
        "height": 500,
        "width": 500
      }
    }
  ],
  "procurement": [
    {
      "costPrice":
      {
        "currencyCode": "USD",
        "amount": "100.00"
      }
    }
  ],
  "issues": [
    {
      "message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): item_weight, theme, item_dimensions, item_diameter",
      "severity": "WARNING",
      "attributeName": "item_diameter",
      "attributeNames": [
        "item_diameter",
        "item_dimensions",
        "item_weight",
        "theme"
      ]
    },
    {
      "message": "Attributes tagged as customer_returns are incomplete. Provide values for the following attribute(s): color, item_dimensions, item_weight",
      "severity": "WARNING",
      "attributeName": "color",
      "attributeNames": [
        "color",
        "item_dimensions",
        "item_weight"
      ]
    }
  ]
}
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

# Tutorial: Create or fully update a listing

Use this tutorial to create or fully update an Amazon listing for a given selling partner and Amazon marketplace.

Prerequisites

To complete this tutorial, you will need:

# Step 1. Submit listings item put request

Call the putListingsItem (opens new window) operation to create or fully update a listing, passing the following parameters:

Request Parameters

Path Parameters

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX A selling partner identifier, such as a merchant account or vendor code.

Type: string

 Yes
sku ABC123 Identifier (stock keeping unit) of the listings item that is unique to the selling partner.

Type: string

 Yes

Query Parameters

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

See the Selling Partner API Developer Guide for the list of Amazon marketplace identifiers.

Type: < string > array(csv)

 Yes
issueLocale en_US Locale for issue localization.

Default: When no locale is provided, the default locale of the first marketplace is used. Localization defaults to en_US when a localized message is not available in the specified locale.

Type: string

 No

Body Parameter

Parameter Example Description Required
body See Example Request The request body schema for the putListingsItem operation.

Type: ListingsItemPutRequest

 Yes

Example Request

PUT https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
	?marketplaceIds=ATVPDKIKX0DER
	&issueLocale=en_US
1
2
3
{
  "productType": "LUGGAGE",
  "requirements": "LISTING",
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_name": [
      {
        "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
        "language_tag": "en_US",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    ...
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Response

A successful response includes the following:

Name Example Description
sku ABC123 Identifier (stock keeping unit) of the listings item that is unique to the selling partner.

Type: string

status ACCEPTED Status of the listings item submission.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 Unique identifier of the listings item submission.

Type: string

issues See Example Response Listings item issues related to the listings item submission.

Type < Issue > array

Example Response

{
  "sku": "ABC123",
  "status": "INVALID",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": [
    {
      "code": "90220",
      "message": "'product_description' is required but not supplied.",
      "severity": "ERROR",
      "attributeNames": [
        "product_description"
      ]
    }
    ...
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Tutorial: Partially update a listing

Use this tutorial to partially update an Amazon listing for a given selling partner and Amazon marketplace using the Listings Items API.

Partial updates are submitted in the form of JSON Patch documents. See https://tools.ietf.org/html/rfc6902 (opens new window) for more details about JSON Patch documents. For Amazon listings, JSON Patch documents can add, replace, or delete entire attributes. Patching content within attributes is not supported.

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 (opens new window) for more information.

  • Approval for the Product Listing role in your developer profile.

  • The Product Listing role selected in the App registration page for your application.

  • For attribute updates, JSON-based listing attribute payloads adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions (opens new window) for the given selling partner, Amazon marketplace, Amazon product type, and attributes.

  • For attribute deletes, JSON-based listing attribute payloads adhering to the JSON Schema provided by the Selling Partner API for Product Type Definitions (opens new window) for the given selling partner, Amazon marketplace, Amazon product type, and attributes with the selector properties of the attributes to delete. Attributes cannot be deleted by name alone, the selector values identify which instance of attributes to delete.

# Step 1. Submit listings item patch request

Call the patchListingsItem (opens new window) operation to partially update a listing, passing the following parameters:

Request Parameters

Path Parameters

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX A selling partner identifier, such as a merchant account or vendor code.

Type: string

 Yes
sku ABC123 Identifier (stock keeping unit) of the listings item that is unique to the selling partner.

Type: string

 Yes

Query Parameters

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

See the Selling Partner API Developer Guide for the list of Amazon marketplace identifiers.

Type: < string > array(csv)

 Yes
issueLocale en_US Locale for issue localization.

Default: When no locale provided, the default locale of the first marketplace is used. Localization defaults to en_US when a localized message is not available in the specified locale.

Type: string

 No

Body Parameter

Parameter Example Description Required
body See Example Request The request body schema for the patchListingsItem operation.

Type: ListingsItemPatchRequest

 Yes

Example Request

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
	?marketplaceIds=ATVPDKIKX0DER
	&issueLocale=en_US
1
2
3
{
  "productType":"LUGGAGE",
  "patches":[
    {
      "op":"replace",
      "path":"/attributes/item_name",
      "value":[
        {
          "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
          "language_tag": "en_US",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    },
    {
      "op":"replace",
      "path":"/attributes/purchasable_offer",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 15.00
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "op":"delete",
      "path":"/attributes/item_type_name",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "language_tag": "en_US"
        }
      ]
    }
  ]
}
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

Response

A successful response includes the following:

Name Example Description
sku ABC123 Identifier (stock keeping unit) of the listings item that is unique to the selling partner.

Type: string

status ACCEPTED Status of the listings item submission.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 Unique identifier of the listings item submission.

Type: string

issues See Example Response Listings item issues related to the listings item submission.

Type < Issue > array

Example Response

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": []
}
1
2
3
4
5
6

# Tutorial: Delete a listing

Use this tutorial to delete an Amazon listing for a given selling partner and Amazon marketplace using the Listings Items API.

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 (opens new window) for more information.

  • Approval for the Product Listing role in your developer profile.

  • The Product Listing role selected in the App registration page for your application.

# Step 1. Submit listings item delete request

Call the deleteListingsItem (opens new window) operation to delete a listing, passing the following parameters:

Request Parameters

Path Parameters

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX A selling partner identifier, such as a merchant account or vendor code.

Type: string

 Yes
sku ABC123 Identifier (stock keeping unit) of the listings item that is unique to the selling partner.

Type: string

 Yes

Query Parameters

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

See the Selling Partner API Developer Guide for the list of Amazon marketplace identifiers.

Type: < string > array(csv)

 Yes
issueLocale en_US Locale for issue localization.

Default: When no locale provided, the default locale of the first marketplace is used. Localization defaults to en_US when a localized message is not available in the specified locale.

Type: string

 No

Example Request

DELETE https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
	?marketplaceIds=ATVPDKIKX0DER
	&issueLocale=en_US
1
2
3

Response

A successful response includes the following:

Name Example Description
sku ABC123 Identifier (stock keeping unit) of the listings item that is unique to the selling partner.

Type: string

status ACCEPTED Status of the listings item submission.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 Unique identifier of the listings item submission.

Type: string

issues See Example Response Listings item issues related to the listings item submission.

Type < Issue > array

Example Response

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "issues": []
}
1
2
3
4
5
6

# Submitting images and other media attributes

The Listings Items API accepts product images and other media content attributes from the following sources:

  • Publicly accessible Amazon S3 bucket content downloaded through HTTP or HTTPS URL
  • Publicly accessible Amazon CloudFront distribution content downloaded through HTTP or HTTPS URL
  • Private Amazon S3 bucket content downloaded through S3 URL (for example, s3://bucket-name/object-name.jpg)

Images hosted on third-party servers are not supported.

If you use a private Amazon S3 bucket, you must also configure your Amazon S3 bucket policy to allow the GetObject and ListBucket operations on the IAM Role accessing the bucket (arn:aws:iam::368641386589:role/Media-Download-Role). See the following S3 bucket policy for an example.

Private Amazon S3 content is treated as immutable, meaning you cannot change the content for an Amazon S3 object key. New media content requires a new Amazon S3 object key. This convention provides the benefit of improved processing times and avoids the cost of redundant downloads in case listing submissions are re-processed.

The following is an example Amazon S3 bucket policy enabling the required operations on a bucket named bucket-name:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::bucket-name/*",
                "arn:aws:s3:::bucket-name"
            ],
            "Principal": {
                "AWS": [
                    "arn:aws:iam::368641386589:role/Media-Download-Role"
                ]
            }
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Listings Restrictions API v2021-08-01