Retrieve details about a listing for single or multiple Amazon stores

Learn how to return detailed information about an Amazon listing for a given selling partner and single or multiple Amazon stores in the same region. The details returned can include a number of optional datasets that provide important information about the state of the listing.

📘

Note

The getListingsItem operation now supports multiple marketplaceIds within the same region in a single request. Previously, you could only specify a single marketplaceIds per call. With this update, you can retrieve listing information for a SKU across all requested Amazon stores in the same region with one API call, eliminating the need for multiple sequential requests. Single marketplaceIds requests continue to work as before.

The marketplaceIds parameter accepts a maximum of 12 Amazon stores per request.

This feature is available for sellers only. Vendor accounts are not supported because each vendor code is associated with a single marketplaceIds.

🚧

Important

The new LISTINGS_ITEM_STATUS_CHANGE notification mentioned in the following paragraphs is available only to sellers. The LISTINGS_ITEM_ISSUES_CHANGE notification is available to sellers and vendors.

For example, if you have subscribed to receive the LISTINGS_ITEM_ISSUES_CHANGE notification using the Selling Partner API for Notifications (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 dataset.

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 might want to get the issues dataset to determine the reason for the search suppression.

For another example, if the LISTINGS_ITEM_STATUS_CHANGE notification does not indicate that the listing is buyable (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 dataset.

In general, the datasets available using the includedData parameter helps you better understand the status of the listing. The datasets available include summary information, contributed attributes, issues, offer information (sellers), fulfillment availability (sellers), and procurement details (vendors).

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications 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.

Submit listings item GET request

Call the getListingsItem operation to return details about a listings item.

Example response

The following example shows a getListingsItem response with two marketplaceIds (ATVPDKIKX0DER and A2EUQ1WTGCTBG2):

{
  "sku": "GM-ZDPI-9B4E",
  "summaries": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "asin": "B071VG5N9D",
      "productType": "LUGGAGE",
      "conditionType": "new_new",
      "status": ["BUYABLE"],
      "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
      }
    },
    {
      "marketplaceId": "A2EUQ1WTGCTBG2",
      "asin": "B071VG5N9D",
      "productType": "LUGGAGE",
      "conditionType": "new_new",
      "status": [],
      "itemName": "Valise rigide à roulettes pour bagage à main",
      "createdDate": "2021-02-02T01:00:00Z",
      "lastUpdatedDate": "2021-03-05T00:00:00Z",
      "mainImage": {
        "link": "https://www.example.com/luggage.png",
        "height": 500,
        "width": 500
      }
    }
  ],
  "attributes": {
    "total_hdmi_ports": [
      {
        "value": 4,
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "value": 4,
        "marketplace_id": "A2EUQ1WTGCTBG2"
      }
    ],
    "resolution": [
      {
        "language_tag": "en_US",
        "value": "4K",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "language_tag": "en_US",
        "value": "4K",
        "marketplace_id": "A2EUQ1WTGCTBG2"
      }
    ],
    "item_weight": [
      {
        "unit": "pounds",
        "value": 107.6,
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "unit": "pounds",
        "value": 107.6,
        "marketplace_id": "A2EUQ1WTGCTBG2"
      }
    ],
    "product_subcategory": [
      {
        "value": "50400120",
        "marketplace_id": "ATVPDKIKX0DER"
      },
      {
        "value": "50400120",
        "marketplace_id": "A2EUQ1WTGCTBG2"
      }
    ]
  },
  "offers": [
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "offerType": "B2C",
      "price": {
        "currencyCode": "USD",
        "amount": "100.00"
      },
      "audience": {
        "value": "ALL",
        "displayName": "Sell on Amazon"
      }
    },
    {
      "marketplaceId": "A2EUQ1WTGCTBG2",
      "offerType": "B2C",
      "price": {
        "currencyCode": "CAD",
        "amount": "130.00"
      },
      "audience": {
        "value": "ALL",
        "displayName": "Sell on Amazon"
      }
    }
  ],
  "fulfillmentAvailability": [
    {
      "fulfillmentChannelCode": "DEFAULT",
      "quantity": 100
    }
  ],
  "issues": [
    {
      "code": "18027",
      "message": "We believe the main image has text, logo, graphic, or watermark that is not permitted for this product type. Submit a compliant image to lift the suppression. Also refer to Product image requirements.",
      "severity": "ERROR",
      "categories": ["INVALID_IMAGE"],
      "enforcements": {
        "actions": [
          {
            "action": "SEARCH_SUPPRESSED"
          }
        ],
        "exemption": {
          "status": "EXEMPT_UNTIL_EXPIRY_DATE",
          "expiryDate": "2025-05-28T00:36:48.914Z"
        }
      },
      "marketplaceIds": ["ATVPDKIKX0DER", "A2EUQ1WTGCTBG2"]
    }
  ]
}