Overview

You can update Amazon listing images (main image, gallery images, and variation swatch) through DataDoe Actions. Images are not sent as raw bytes in the Action payload. Instead:

1. Upload images as Files in the LISTING_IMAGES group.
2. Reference file UUIDs in the images field of an AMAZON_LISTINGS_UPDATE change.
3. Let DataDoe validate the files, prepare Amazon-compatible media locations, and submit the update feed.

This page describes the full workflow, including MCP and REST API examples.

You are responsible for the results of Actions you run. Review every payload before running an Action.

Prerequisites

Before changing listing images:

1. Enable AMAZON_LISTINGS_UPDATE in Settings > Actions.
2. Set the target Seller or Vendor to Read and write on the Accounts page.
3. Upload listing images as LISTING_IMAGES files (see Files).
4. Confirm each file has status UPLOADED and has not expired.

General workflow

Step 1 - Upload images

Upload one file per image slot you want to change. Use PNG, JPG, or TIFF (max 32 MB). The default TTL is 12 hours. Start the Action before files expire.

See Files for upload instructions via MCP, API, or the Files page.

Step 2 - Build the Action payload

Add an images object to each change in details.changes. Each key is an image slot. Each value controls that slot:

You can update text fields (name, bullet points, and so on) in the same change, or send an images-only change with just sku and images.

Step 3 - Validate with dry run

Run the Action with dryRun: true first. DataDoe checks file existence, group, status, expiry, and seller or vendor scope without submitting to Amazon.

Step 4 - Start the Action

Run the same payload with dryRun: false, or omit dryRun. DataDoe queues the listing feed.

Step 5 - Wait for completion

Poll the Action until the status is terminal (COMPLETED, FAILED, or CANCELLED). After DataDoe submits the feed, Amazon may take 5 minutes to a few hours to process Seller Central and Vendor Central listing changes.

Image slots

Each slot in the images object maps to an Amazon listing attribute:

Only include slots you want to change. Omitted slots stay unchanged on Amazon.

Seller vs Vendor rules

Vendor accounts cannot use null to remove images. Removal attempts return a validation error.

File requirements at Action time

Each file UUID you reference must:

• exist and belong to your Organization
• belong to the same seller or vendor and connection as the Action
• be in the LISTING_IMAGES group
• have status UPLOADED
• not be past expiresAt

DataDoe re-validates files when the Action executes, not only during dry run. If a file expires between validation and execution, the Action fails.

MCP example - replace main and gallery images

This example uploads two images, then updates a listing.

1. Upload the main image

1{
2    "tool": "files_create",
3    "arguments": {
4        "name": "main-photo.png",
5        "group": "LISTING_IMAGES",
6        "type": "PNG",
7        "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
8        "ttlHours": 12,
9        "contentBase64": "BASE64_MAIN_IMAGE"
10    }
11}

Save file.id from the response as MAIN_FILE_ID.

2. Upload a gallery image

1{
2    "tool": "files_create",
3    "arguments": {
4        "name": "gallery-1.png",
5        "group": "LISTING_IMAGES",
6        "type": "PNG",
7        "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
8        "ttlHours": 12,
9        "contentBase64": "BASE64_GALLERY_IMAGE"
10    }
11}

Save file.id as GALLERY_FILE_ID.

3. Validate the listing update

1{
2    "tool": "actions_start",
3    "arguments": {
4        "type": "AMAZON_LISTINGS_UPDATE",
5        "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
6        "dryRun": true,
7        "details": {
8            "changes": [
9                {
10                    "sku": "MY-SKU-001",
11                    "images": {
12                        "mainImage": "MAIN_FILE_ID",
13                        "image1": "GALLERY_FILE_ID"
14                    }
15                }
16            ]
17        }
18    }
19}

Confirm validation.valid is true and issues is empty.

4. Start the Action

Repeat the same actions_start call with dryRun: false, or omit dryRun.

5. Poll status

1{
2    "tool": "actions_get",
3    "arguments": {
4        "actionId": "ACTION_ID_FROM_START_RESPONSE"
5    }
6}

MCP example - remove a gallery image (Seller Central)

1{
2    "tool": "actions_start",
3    "arguments": {
4        "type": "AMAZON_LISTINGS_UPDATE",
5        "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
6        "dryRun": true,
7        "details": {
8            "changes": [
9                {
10                    "sku": "MY-SKU-001",
11                    "images": {
12                        "image2": null
13                    }
14                }
15            ]
16        }
17    }
18}

After dry-run validation succeeds, start the Action without dryRun.

MCP example - multiple SKUs in one Action

Each change can have its own images object. Changes without images are not affected by image preparation.

1{
2    "tool": "actions_start",
3    "arguments": {
4        "type": "AMAZON_LISTINGS_UPDATE",
5        "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
6        "dryRun": true,
7        "details": {
8            "changes": [
9                {
10                    "sku": "SKU-A",
11                    "images": {
12                        "mainImage": "FILE_ID_FOR_SKU_A"
13                    }
14                },
15                {
16                    "sku": "SKU-B",
17                    "name": "Updated title only",
18                    "language_tag": "en_US"
19                },
20                {
21                    "sku": "SKU-C",
22                    "images": {
23                        "image1": "FILE_ID_FOR_SKU_C_GALLERY"
24                    }
25                }
26            ]
27        }
28    }
29}

Only SKU-A and SKU-C receive image patches. SKU-B updates the title only.

REST API example - replace images

1. Create and upload files

1POST /api/v1/files
2Content-Type: application/json
3X-Api-Key: YOUR_API_KEY
4
5{
6  "name": "main-photo.png",
7  "group": "LISTING_IMAGES",
8  "type": "PNG",
9  "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
10  "ttlHours": 12
11}

The response includes file.id and uploadUrl. Upload the bytes:

1PUT {uploadUrl}
2Content-Type: image/png
3
4<binary image data>

Repeat for each image. Confirm GET /api/v1/files/{fileId} returns "status": "UPLOADED".

2. Validate the Action

1POST /api/v1/actions
2Content-Type: application/json
3X-Api-Key: YOUR_API_KEY
4
5{
6  "type": "AMAZON_LISTINGS_UPDATE",
7  "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
8  "dryRun": true,
9  "details": {
10    "changes": [
11      {
12        "sku": "MY-SKU-001",
13        "images": {
14          "mainImage": "MAIN_FILE_ID",
15          "image1": "GALLERY_FILE_ID"
16        }
17      }
18    ]
19  }
20}

3. Start the Action

Send the same body with "dryRun": false.

4. Poll status

1GET /api/v1/actions/{actionId}
2X-Api-Key: YOUR_API_KEY

REST API example - remove an image (Seller Central)

1POST /api/v1/actions
2Content-Type: application/json
3X-Api-Key: YOUR_API_KEY
4
5{
6  "type": "AMAZON_LISTINGS_UPDATE",
7  "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID",
8  "dryRun": true,
9  "details": {
10    "changes": [
11      {
12        "sku": "MY-SKU-001",
13        "images": {
14          "image3": null
15        }
16      }
17    ]
18  }
19}

Related documentation

• Files for uploading and managing utility files.
• Actions for Actions overview, limits, and enablement.
• DataDoe API docs (opens in a new tab) for full request schemas for Files and Actions.