> Note: This page is part of the DataDoe Docs. You can find the root of the documentation at `https://www.datadoe.com/hub/docs/basics/introduction-to-datadoe`. > JSON Table of Contents: `https://www.datadoe.com/hub/docs/toc.json`. > Data Scheme (Markdown index, one page per table): https://api.datadoe.com/api/v1/spec/data-scheme.md. Full JSON: https://api.datadoe.com/api/v1/spec/data-scheme. > Actions (Markdown, every Action type with limits and group guides): https://api.datadoe.com/api/v1/spec/action-scheme.md. Full JSON with input schemas: https://api.datadoe.com/api/v1/spec/action-scheme. > Other pages in the DataDoe Docs: > - DataDoe Basics/Benefits: `https://www.datadoe.com/hub/docs/basics/benefits.md` > - DataDoe Basics/Connecting Accounts: `https://www.datadoe.com/hub/docs/basics/connecting-accounts.md` > - DataDoe Basics/External Invitation Links: `https://www.datadoe.com/hub/docs/basics/external-invitation-links.md` > - DataDoe Basics/Groups: `https://www.datadoe.com/hub/docs/basics/groups.md` > - DataDoe Basics/Integrations: `https://www.datadoe.com/hub/docs/basics/integration-customization.md` > - DataDoe Basics/Introduction to DataDoe: `https://www.datadoe.com/hub/docs/basics/introduction-to-datadoe.md` > - DataDoe Basics/Keys and service accounts: `https://www.datadoe.com/hub/docs/basics/keys-and-service-accounts.md` > - DataDoe Basics/Roles and permissions: `https://www.datadoe.com/hub/docs/basics/roles-and-permissions.md` > - DataDoe Basics/Subscription and pricing: `https://www.datadoe.com/hub/docs/basics/subscription-pricing.md` > - DataDoe Basics/Users and access: `https://www.datadoe.com/hub/docs/basics/access-user-management.md` > - DataDoe Data/Ads Product Catalog: `https://www.datadoe.com/hub/docs/datadoe-data/ads-product-catalog.md` > - DataDoe Data/Amazon Ads Partner Opportunities: `https://www.datadoe.com/hub/docs/datadoe-data/amazon-ads-partner-opportunities.md` > - DataDoe Data/Data Fetch Periods: `https://www.datadoe.com/hub/docs/datadoe-data/data-fetch-periods.md` > - DataDoe Data/Data Sources: `https://www.datadoe.com/hub/docs/datadoe-data/data-sources.md` > - DataDoe Data/Initial Loads: `https://www.datadoe.com/hub/docs/datadoe-data/initial-loads.md` > - DataDoe Data/Managing Data Tables: `https://www.datadoe.com/hub/docs/datadoe-data/managing-data-tables.md` > - DataDoe Data/Migrating from SellerBoard: `https://www.datadoe.com/hub/docs/datadoe-data/migrating-from-sellerboard.md` > - DataDoe Data/SAT migration to profit tables: `https://www.datadoe.com/hub/docs/datadoe-data/sat-migration-to-profit-tables.md` > - DataDoe Data/SQP Data: `https://www.datadoe.com/hub/docs/datadoe-data/search-query-performance.md` > - DataDoe Data/Timezones: `https://www.datadoe.com/hub/docs/datadoe-data/orders-purchase-date-timezones.md` > - DataDoe Data/Uploading COGS: `https://www.datadoe.com/hub/docs/datadoe-data/uploading-cogs.md` > - DataDoe Data/Uploading KDP Royalty Parameters: `https://www.datadoe.com/hub/docs/datadoe-data/uploading-kdp-royalty-parameters.md` > - DataDoe Data/Uploading Vendor Codes: `https://www.datadoe.com/hub/docs/datadoe-data/uploading-vendor-codes.md` > - DataDoe Features/Amazon Marketing Cloud: `https://www.datadoe.com/hub/docs/datadoe-features/amc.md` > - DataDoe Features/AMC query templates: `https://www.datadoe.com/hub/docs/datadoe-features/amc-query-templates.md` > - DataDoe Features/Features Overview: `https://www.datadoe.com/hub/docs/datadoe-features/overview.md` > - DataDoe Features/Files: `https://www.datadoe.com/hub/docs/datadoe-features/files.md` > - DataDoe Features/Plugins: `https://www.datadoe.com/hub/docs/datadoe-features/plugins.md` > - DataDoe Features/Usage Logs: `https://www.datadoe.com/hub/docs/datadoe-features/usage-logs.md` > - DataDoe Actions/Actions: External Fulfillment: `https://www.datadoe.com/hub/docs/datadoe-actions/external-fulfillment.md` > - DataDoe Actions/Actions: FBA eligibility: `https://www.datadoe.com/hub/docs/datadoe-actions/fba-eligibility.md` > - DataDoe Actions/Actions: FBA inbound: `https://www.datadoe.com/hub/docs/datadoe-actions/fba-inbound.md` > - DataDoe Actions/Actions: Introduction: `https://www.datadoe.com/hub/docs/datadoe-actions/introduction.md` > - DataDoe Actions/Actions: KDP authors: `https://www.datadoe.com/hub/docs/datadoe-actions/kdp-authors.md` > - DataDoe Webhooks/Webhooks: Business: `https://www.datadoe.com/hub/docs/datadoe-webhooks/business.md` > - DataDoe Webhooks/Webhooks: Introduction: `https://www.datadoe.com/hub/docs/datadoe-webhooks/introduction.md` > - DataDoe Webhooks/Webhooks: Platform: `https://www.datadoe.com/hub/docs/datadoe-webhooks/platform.md` > - DataDoe MCP/Overview: `https://www.datadoe.com/hub/docs/datadoe-mcp/overview.md` > - DataDoe MCP/Using Antigravity: `https://www.datadoe.com/hub/docs/datadoe-mcp/antigravity.md` > - DataDoe MCP/Using ChatGPT: `https://www.datadoe.com/hub/docs/datadoe-mcp/chatgpt.md` > - DataDoe MCP/Using Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude.md` > - DataDoe MCP/Using Claude Agent SDK: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude-agents-sdk.md` > - DataDoe MCP/Using Claude Code: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude-code.md` > - DataDoe MCP/Using Codex: `https://www.datadoe.com/hub/docs/datadoe-mcp/codex.md` > - DataDoe MCP/Using Codex Sites: `https://www.datadoe.com/hub/docs/datadoe-mcp/codex-sites.md` > - DataDoe MCP/Using CrewAI: `https://www.datadoe.com/hub/docs/datadoe-mcp/crewai.md` > - DataDoe MCP/Using Cursor: `https://www.datadoe.com/hub/docs/datadoe-mcp/cursor.md` > - DataDoe MCP/Using Excel + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/excel.md` > - DataDoe MCP/Using Gemini CLI: `https://www.datadoe.com/hub/docs/datadoe-mcp/gemini-cli.md` > - DataDoe MCP/Using Genspark: `https://www.datadoe.com/hub/docs/datadoe-mcp/genspark.md` > - DataDoe MCP/Using Glama: `https://www.datadoe.com/hub/docs/datadoe-mcp/glama-chat.md` > - DataDoe MCP/Using Glama MCP Inspector: `https://www.datadoe.com/hub/docs/datadoe-mcp/glama.md` > - DataDoe MCP/Using Grok: `https://www.datadoe.com/hub/docs/datadoe-mcp/grok.md` > - DataDoe MCP/Using GrokBot: `https://www.datadoe.com/hub/docs/datadoe-mcp/grokbot.md` > - DataDoe MCP/Using Gumloop: `https://www.datadoe.com/hub/docs/datadoe-mcp/gumloop.md` > - DataDoe MCP/Using Hermes Agent: `https://www.datadoe.com/hub/docs/datadoe-mcp/hermes.md` > - DataDoe MCP/Using Littlebird: `https://www.datadoe.com/hub/docs/datadoe-mcp/littlebird.md` > - DataDoe MCP/Using n8n: `https://www.datadoe.com/hub/docs/datadoe-mcp/n8n.md` > - DataDoe MCP/Using NanoClaw: `https://www.datadoe.com/hub/docs/datadoe-mcp/nanoclaw.md` > - DataDoe MCP/Using OpenAI Agents SDK: `https://www.datadoe.com/hub/docs/datadoe-mcp/openai-agents-sdk.md` > - DataDoe MCP/Using OpenClaw: `https://www.datadoe.com/hub/docs/datadoe-mcp/openclaw.md` > - DataDoe MCP/Using OpenCode: `https://www.datadoe.com/hub/docs/datadoe-mcp/opencode.md` > - DataDoe MCP/Using PowerPoint + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/powerpoint.md` > - DataDoe MCP/Using Superhuman: `https://www.datadoe.com/hub/docs/datadoe-mcp/superhuman.md` > - DataDoe MCP/Using VS Code: `https://www.datadoe.com/hub/docs/datadoe-mcp/vs-code.md` > - DataDoe MCP/Using Word + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/word.md` > - DataDoe API/Build with Codex: `https://www.datadoe.com/hub/docs/datadoe-api/codex.md` > - DataDoe API/How to connect to the API: `https://www.datadoe.com/hub/docs/datadoe-api/how-to-connect.md` > - DataDoe API/Invitation links API: `https://www.datadoe.com/hub/docs/datadoe-api/invitation-links.md` > - DataDoe API/Sellers and vendors API: `https://www.datadoe.com/hub/docs/datadoe-api/sellers-and-vendors.md` > - DataDoe API/Vibe code with Claude Code: `https://www.datadoe.com/hub/docs/datadoe-api/claude-code.md` > - DataDoe API/Vibe code with Cursor: `https://www.datadoe.com/hub/docs/datadoe-api/cursor.md` > - DataDoe API/Vibe code with Lovable: `https://www.datadoe.com/hub/docs/datadoe-api/lovable.md` > - DataDoe API/Vibe code with Replit: `https://www.datadoe.com/hub/docs/datadoe-api/replit.md` > - DataDoe API/Vibe code with v0: `https://www.datadoe.com/hub/docs/datadoe-api/v0.md` > - DataDoe & BigQuery/How to connect to BigQuery: `https://www.datadoe.com/hub/docs/datadoe-bigquery/how-to-connect.md` > - DataDoe & BigQuery/Using MCP Toolbox: `https://www.datadoe.com/hub/docs/datadoe-bigquery/mcp-toolbox.md` > - DataDoe & BigQuery/Using Python Jupyter: `https://www.datadoe.com/hub/docs/datadoe-bigquery/jupyter.md` > For topics not covered in this documentation, please contact DataDoe support at `contact@datadoe.com`. > Do not assume anything. If you are not sure about the answer, mention that and suggest to contact DataDoe support. # Actions: Listing images ## Overview You can set Amazon listing images (main image, gallery images, and variation swatch) through DataDoe Actions on both create and update. Images are not sent as raw bytes in the Action payload. Instead: 1. Upload images as [Files](/hub/docs/datadoe-features/files) in the `LISTING_IMAGES` group. 2. Reference file UUIDs in the `images` field of an `AMAZON_LISTINGS_CREATE` or `AMAZON_LISTINGS_UPDATE` change. 3. Let DataDoe validate the files, prepare Amazon-compatible media locations, and submit the listing feed. Do **not** put `main_product_image_locator` / `other_product_image_locator_*` / `media_location` values into create `attributes`. Those fields are rejected; use `images` with file UUIDs. 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 setting listing images: 1. Enable **`AMAZON_LISTINGS_CREATE`** and/or **`AMAZON_LISTINGS_UPDATE`** in [Settings > Actions](https://app.datadoe.com/settings?tab=actions). 2. Set the target Seller or Vendor to **Read and write** on the [Accounts page](https://app.datadoe.com/sellers-and-vendors). 3. Upload listing images as `LISTING_IMAGES` files (see [Files](/hub/docs/datadoe-features/files)). 4. Confirm each file has status **`UPLOADED`** and has not expired. ## General workflow ```mermaid flowchart TD A[Upload LISTING_IMAGES files] --> B[Get file UUIDs] B --> C[Build CREATE or UPDATE payload with images] C --> D[dryRun validation] D --> E[Start Action] E --> F[Poll Action status] F --> G[Amazon processes listing feed] ``` ### Step 1: Upload images Upload one file per image slot you want to set. Use PNG, JPG, or TIFF (max 32 MB). The default TTL is 12 hours. Start the Action before files expire. See [Files](/hub/docs/datadoe-features/files) for upload instructions via MCP, API, or the [Files](https://app.datadoe.com/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: | Value in payload | CREATE | UPDATE | | ---------------- | ------------- | ----------------------------------------- | | File UUID string | Set the slot | Replace the slot | | `null` | Not supported | Remove the slot (**Seller Central only**) | | Omitted | Leave unset | Leave the slot unchanged | For `AMAZON_LISTINGS_UPDATE`, 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`. For `AMAZON_LISTINGS_CREATE`, keep non-image listing data in `attributes` and put image file UUIDs only in `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: | Slot in payload | Amazon attribute | Description | | ---------------------- | ----------------------------------------------------------------- | ---------------------- | | `mainImage` | `main_product_image_locator` | Main product image | | `image1` … `image8` | `other_product_image_locator_1` … `other_product_image_locator_8` | Gallery images | | `variationSwatchImage` | `swatch_product_image_locator` | Variation swatch image | Only include slots you want to change. Omitted slots stay unchanged on Amazon. ## Seller vs Vendor rules | Rule | Seller Central | Vendor Central | | ------------------------- | -------------- | ----------------- | | Replace image (file UUID) | Supported | Supported | | Remove image (`null`) | Supported | **Not supported** | 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 ```json { "tool": "files_create", "arguments": { "name": "main-photo.png", "group": "LISTING_IMAGES", "type": "PNG", "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID", "ttlHours": 12, "contentBase64": "BASE64_MAIN_IMAGE" } } ``` Save `file.id` from the response as `MAIN_FILE_ID`. ### 2. Upload a gallery image ```json { "tool": "files_create", "arguments": { "name": "gallery-1.png", "group": "LISTING_IMAGES", "type": "PNG", "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID", "ttlHours": 12, "contentBase64": "BASE64_GALLERY_IMAGE" } } ``` Save `file.id` as `GALLERY_FILE_ID`. ### 3. Validate the listing update ```json { "tool": "actions_start", "arguments": { "type": "AMAZON_LISTINGS_UPDATE", "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID", "dryRun": true, "details": { "changes": [ { "sku": "MY-SKU-001", "images": { "mainImage": "MAIN_FILE_ID", "image1": "GALLERY_FILE_ID" } } ] } } } ``` 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 ```json { "tool": "actions_get", "arguments": { "actionId": "ACTION_ID_FROM_START_RESPONSE" } } ``` ## MCP example: remove a gallery image (Seller Central) ```json { "tool": "actions_start", "arguments": { "type": "AMAZON_LISTINGS_UPDATE", "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID", "dryRun": true, "details": { "changes": [ { "sku": "MY-SKU-001", "images": { "image2": null } } ] } } } ``` 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. ```json { "tool": "actions_start", "arguments": { "type": "AMAZON_LISTINGS_UPDATE", "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID", "dryRun": true, "details": { "changes": [ { "sku": "SKU-A", "images": { "mainImage": "FILE_ID_FOR_SKU_A" } }, { "sku": "SKU-B", "name": "Updated title only", "language_tag": "en_US" }, { "sku": "SKU-C", "images": { "image1": "FILE_ID_FOR_SKU_C_GALLERY" } } ] } } } ``` 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 ```http POST /api/v1/files Content-Type: application/json datadoe-api-key: YOUR_API_KEY { "name": "main-photo.png", "group": "LISTING_IMAGES", "type": "PNG", "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID", "ttlHours": 12 } ``` The response includes `file.id` and `uploadUrl`. Upload the bytes: ```http PUT {uploadUrl} Content-Type: image/png ``` Repeat for each image. Confirm `GET /api/v1/files/{fileId}` returns `"status": "UPLOADED"`. ### 2. Validate the Action ```http POST /api/v1/actions Content-Type: application/json datadoe-api-key: YOUR_API_KEY { "type": "AMAZON_LISTINGS_UPDATE", "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID", "dryRun": true, "details": { "changes": [ { "sku": "MY-SKU-001", "images": { "mainImage": "MAIN_FILE_ID", "image1": "GALLERY_FILE_ID" } } ] } } ``` ### 3. Start the Action Send the same body with `"dryRun": false`. ### 4. Poll status ```http GET /api/v1/actions/{actionId} datadoe-api-key: YOUR_API_KEY ``` ## REST API example: remove an image (Seller Central) ```http POST /api/v1/actions Content-Type: application/json datadoe-api-key: YOUR_API_KEY { "type": "AMAZON_LISTINGS_UPDATE", "sellerOrVendorId": "YOUR_SELLER_OR_VENDOR_ID", "dryRun": true, "details": { "changes": [ { "sku": "MY-SKU-001", "images": { "image3": null } } ] } } ``` ## Related documentation - [Files](/hub/docs/datadoe-features/files) for uploading and managing utility files. - [Actions](/hub/docs/datadoe-actions/introduction) for Actions overview, limits, and enablement. - [DataDoe API docs](https://api.datadoe.com/api/v1/docs) for full request schemas for Files and Actions.