Submit media attributes

Learn how to submit images and other media attributes using the Listings Items API.

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.
• All images to comply with Amazon's product image requirements.

Submit 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 that are publicly available to Amazon.

⭐

Tip

For optimal processing performance, host your media on AWS (such as Amazon S3 or Amazon CloudFront) or other highly available content delivery network (CDN) services.
If you use a private Amazon S3 bucket, you must also configure your Amazon S3 bucket policy to allow the IAM role (arn:aws:iam:XXXXXXXXXXXX:role/Media-Download-Role) to call the GetObject and ListBucket operations on the bucket. Refer to 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::XXXXXXXXXXXX:role/Media-Download-Role"
        ]
      }
    }
  ]
}

Supported image variants

The Listings Items API supports the following image variants:

Supported image variants and their requirements differ by product type and marketplace. To determine which image attributes are available for your product type, call the getDefinitionsProductType operation.

The response includes all supported image attributes along with their constraints, such as required vs. optional, accepted formats, and resolution requirements.

📘

Note

Seller Central's Image Manager supports additional image variants that are not available through the Listings Items API. Only the preceding variants can be submitted programmatically.

Submit multiple images in a single request

You can include all image attributes in a single putListingsItem request or JSON_LISTINGS_FEED submission:

{
  "productType": "SHIRT",
  "attributes": {
    "main_product_image_locator": [
      {"media_location": "https://your-bucket.s3.amazonaws.com/main.jpg"}
    ],
    "other_product_image_locator_1": [
      {"media_location": "https://your-bucket.s3.amazonaws.com/angle.jpg"}
    ],
    "other_product_image_locator_2": [
      {"media_location": "https://your-bucket.s3.amazonaws.com/lifestyle.jpg"}
    ],
    "swatch_product_image_locator": [
      {"media_location": "https://your-bucket.s3.amazonaws.com/swatch.jpg"}
    ]
  }
}

📘

Note

Using the JSON_LISTINGS_FEED, you can submit images for multiple SKUs in a single feed document. This allows bulk image updates across your catalog.