Actions: Introduction

What are DataDoe Actions?

Actions let your AI agents and integrations act on your Amazon account through DataDoe. They can read data and make changes, such as updating listings, cancelling orders, confirming shipments, and managing ads. Every Action runs through DataDoe MCP or the REST API and is monitored and auditable. Every Action type supports a dry run that validates the request without sending it to Amazon. See Subscription & Pricing for Action costs.

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

Users with Manage Actions for allowed Sellers and Vendors can select the Sellers and Vendors store icon beside an Action in Settings > Actions. The icon shows how many accounts are blocked. Turn off an account to block that Action for the account. Accounts are allowed by default, and the Organization must also have the Action enabled. Users still need the permissions and account access required to run the Action. Queued Actions check account restrictions before execution.

How do Actions protect your Amazon account?

Live Actions reach your Amazon account only after your Organization allows them at every level:

• Off until you enable it. Every Action type, including each new one, is disabled until an authorized member enables it in Settings > Actions (opens in a new tab).
• Write access per account. Write Actions run only on Sellers and Vendors whose access level is Read and write. Accounts with Read only access accept only read Actions.
• Permissions per user and Action. The user or service account needs the Execute Actions permission, access to the Action type, and access to the Seller or Vendor. You can also block an Action for selected Sellers and Vendors.
• Gated personal data. PII Actions require Amazon PII Data Access for your Organization and the Access PII data permission.
• Test before you run. Every Action type supports a dry run. Listing, A+ Content, and Multi-Channel Fulfillment changes also have previews that Amazon validates without applying the change. See How to test an Action before it changes Amazon?
• Safe retries. With an optional idempotencyKey, a retried request returns the original Action instead of running or charging again. See How to retry a live Action safely?
• Limits and history. Live Action limits cap how much can run at the same time. Every live Action is recorded in your Action history, which you can read with actions_list or GET /actions.

dryRun is optional and defaults to false. Existing integrations and AI agents send live requests without this field, and a dry-run default would silently turn their Actions into validations. Live writes are protected by the settings above instead, and we recommend a dry run before every live write.

How to test an Action before it changes Amazon?

Set "dryRun": true on the same request that you plan to run live. Every Action type supports it, read and write.

A dry run checks the request the same way as a live start:

• the details schema and the item limit
• the Execute Actions permission, access to the Action type, and access to the Seller or Vendor, including account restrictions
• whether the Seller or Vendor's connection supports the Action type
• PII access, for PII Actions
• for listing changes with a productType, the current product-type schema for that seller and marketplace

A dry run does not send the Action to Amazon or create an Action. It does not spend AI Tokens and does not count toward live Action limits. It also works while the Action type is still disabled for your Organization. A dry run of a write Action needs only Read only for Execute Actions and does not need Read and write access for the account. You can build and test a flow before anyone allows live writes.

A valid request returns "status": "VALIDATED" with "actionId": null. A request that fails a check returns the same error as a live start, such as HTTP 400 for invalid details or HTTP 403 for missing access. Product-type schema and some Amazon Ads checks return "status": "BLOCKED_INVALID_INPUT" with the problems in validation.issues.

1{
2    "type": "AMAZON_LISTINGS_PRICING_UPDATE",
3    "sellerOrVendorId": "<authorized-seller-or-vendor-id>",
4    "dryRun": true,
5    "details": {
6        "changes": [{ "sku": "MY-SKU-001", "price": 24.99 }]
7    }
8}

A dry run checks the request in DataDoe. To have Amazon check a change without applying it, run its preview Action. Previews are read Actions: the Action type must be enabled, and they cost the same as other read Actions.

We recommend this flow for every write:

1. Run the request with "dryRun": true and fix any issues.
2. If the Action has a preview, run the preview and review Amazon's response.
3. Start the Action with "dryRun": false and an idempotencyKey.
4. Poll the Action until it finishes and review its result.

How to enable Actions?

All Action types are disabled by default for every Organization. You can enable specific Action types in Settings > Actions (opens in a new tab). When an Action type is disabled, MCP and API reject requests to run Actions of this type, but dryRun is still possible. New Action types are disabled by default.

To start a write Action for a Seller or Vendor, set its access level to Read and write on the Accounts page (opens in a new tab). Read Actions can run when the access level is Read only.

Actions marked PII require Amazon PII Data Access for your Organization and your role's Access PII data permission to run, including for dryRun, and to read their history, results, and shipping-label Files. These Actions can contain personal data in requests, results, or generated documents. Some other Actions can also process personal data without requiring PII access. DataDoe removes personal data from both groups 30 days after the Action is created. The Action stays in history without its request, result, or generated documents. In the API and MCP, details is {"piiRedacted": true} and result is null. A null result means DataDoe removed that personal data, so leave the completed Action as it is. An Action that is still running keeps that data until it finishes.

AMAZON_ORDERS_FIND requires PII access when includedData contains BUYER, RECIPIENT, or TAX. FBA inbound, MCF, MCF delivery-offer previews, and FBA removal-order Actions do not require PII access. DataDoe still removes personal data from these Action records and related logs and files after 30 days.

Who can run an Action?

Enabling an Action for the Organization and granting access to it are separate settings. To run an Action, the user or service account needs:

• Execute Actions at the required level: Read only for read Actions and validation previews, or Read & write for live write Actions
• access to the specific Action type
• access to the selected Seller or Vendor

Admins choose All or Selected Actions for roles and service accounts in Settings > Permissions. Use Access beside an Action in Settings > Actions to assign users, roles, or service accounts. An assignment applies to every Seller and Vendor the recipient can access.

Admins can delegate Manage Action access. Delegates can assign users and roles only to Actions they can access. Only Admins can change service account assignments. These grants do not enable the Action or grant permission to execute it.

Catalog names and payload schemas remain visible. MCP schema responses include accessAllowed to show whether the caller has access to that Action type. This does not replace the execution permission or account checks. Dry runs require Action and account access too, even when the Action is disabled for live execution.

Action access is independent of table access. An allowed Action can return results even if the caller cannot access a table containing similar data. History, results, and generated documents require access to the Action and its account. Queued work rechecks its execution owner's access before running.

Changing which Actions are enabled for the Organization requires Enabled Actions: Read & write and All Sellers and Vendors access. See Manage roles and access for more about these controls.

How to run Actions?

Using MCP

1. Connect DataDoe to Claude, ChatGPT, or another MCP-capable agent.
2. Get the payload schema, access mode (READ or WRITE), whether the Action type needs PII access (requiresPii), whether the Action type is enabled for the Organization (enabled), and the start tool (actions_start) with actions_details_schema_get. When enabled is false, an authorized Organization member turns the type on in Settings > Actions (opens in a new tab).
3. Use the payload schema, data from DataDoe, and other inputs to build your Action payload.
4. Validate the payload with dryRun=true using actions_start for both Read and Write Actions. See How to test an Action before it changes Amazon?
5. Start the Action with the same tool, dryRun=false, and an idempotencyKey, so you can retry it safely.
6. Poll for the Action status using the actions_get tool. While the Action is processing, the response summary gives the recommended poll interval: 2 seconds for small requests that usually finish within seconds, such as listing lookups and previews, and 30 seconds for the others.
7. Read the Action result in the result field of the Action response.

Read Actions and write Actions appear in the same Action history. A standard read Action costs less than a write Action. A live write Action needs Read and write access. A live read Action can run with Read only access. The schema tool returns access (READ or WRITE), requiresPii, and startTool (actions_start) alongside the payload schema. See Subscription & Pricing.

DataDoe uses the /mcp/v1 endpoint for all MCP clients.

You can also get past Actions within your current access using the actions_list tool.

Using API

The easiest way to run Actions with the API is to paste this page URL into your coding AI agent and ask it to generate the code for you.

Authenticate every REST request with the datadoe-api-key header. Do not use X-Api-Key or Authorization.

1POST /api/v1/actions
2Content-Type: application/json
3datadoe-api-key: YOUR_API_KEY

1. Set up your DataDoe API connection.
2. Check the payload schema for the Action type you want to run in the request body schema (opens in a new tab) for the POST /actions resource.
3. Use the payload schema, data from DataDoe, and other inputs to build your Action payload.
4. Validate the Action payload using the POST /actions resource with dryRun=true.
5. Start the Action using the POST /actions resource with dryRun=false and an idempotencyKey, so you can retry it safely.
6. Poll for the Action status using the GET /actions/<action_id> resource.
7. Read the Action result in the result field of the Action response.

You can also get past Actions within your current access using the GET /actions resource.

All details about the API are available in the DataDoe API docs (opens in a new tab).

How to retry a live Action safely?

Without a key, every live request starts a new Action. If a request times out and you send it again, the operation can run twice. To prevent this, add an optional idempotencyKey to any read or write Action. It is recommended for writes and automatic retries. The key is optional so that clients that omit it keep their existing behavior.

Use a UUID or a stable ID for one business operation. A key accepts 1 to 128 case-sensitive ASCII letters, digits, periods, underscores, colons, or hyphens. Do not include credentials or personal data. Keys are scoped to your Organization and user or service account, including across API and MCP and credential rotation.

1{
2    "type": "AMAZON_ADS_CAMPAIGNS_FIND",
3    "sellerOrVendorId": "<authorized-seller-or-vendor-id>",
4    "dryRun": false,
5    "idempotencyKey": "campaign-check:97b79f95-9dfe-4d23-a253-1cb2f89a1a77",
6    "details": {
7        "campaignQuery": {
8            "adProductFilter": { "include": ["SPONSORED_PRODUCTS"] }
9        }
10    }
11}

After a timeout, repeat the entire original request with the same key. DataDoe returns the original Action's current status and result, with idempotency.replayed set to true. The first accepted request returns false. A replayed read returns the original data. Use a new key when you need fresh data or intend a different operation.

Using the same key for a different request returns HTTP 409 with ACTION_IDEMPOTENCY_CONFLICT. Keys remain consumed after failed or partially completed Actions. If the original result was removed under data retention, a matching retry returns HTTP 410 with ACTION_IDEMPOTENCY_RESULT_EXPIRED. Receipts do not expire automatically. Current permissions still apply to every retry.

A dry run validates the key without reserving it. This protection prevents duplicate DataDoe submissions, charges, and worker starts. It cannot determine whether Amazon accepted a write that timed out. Review the original Action before starting another operation with a new key.

What are the live Actions limits?

DataDoe limits how many live Actions you can have at the same time:

• up to 500 per organization,
• and up to 25 per Seller or Vendor connection.

If you exceed a limit, starting a new Action is rejected (HTTP 429 for the API). A live Action is any Action that is PENDING, IN_PROGRESS, or WAITING_EXTERNAL_PROCESSING. Actions sent in dryRun mode are not counted toward these limits.

Wait for existing Actions to complete or combine multiple operations into a single Action request to stay within the limits.

What are the available operation types?

The following operation types are available:

• Write: Create, update, or delete an entity.
• Read: Read an entity to verify its state before or after an operation.

Read operations in Actions are only for verification steps in flows built with Actions. They should not be used for analysis, planning changes, or reporting. For these tasks, use our data tables.

How much does an Action cost?

Group items into one Action. A standard read Action costs 0.5 AI Tokens for up to 100 items, then 0.25 AI Tokens for each additional 100 items. A standard write Action costs 3 AI Tokens for up to 100 items, then 1 AI Token for each additional 100 items. Each separate Action pays the starting price again. A dry run does not spend AI Tokens. FBA inbound Actions have fixed prices of 0.1 AI Token per read Action and 0.3 AI Token per write Action, regardless of item or shipment count. Campaign, ad group, target, ad, ad association, ad extension, portfolio, brand, and communication FIND Actions count as 1 item per call. Per-audience AMC prices and free AMC audience Actions stay the same.

When a FIND Action's entity is in the DataDoe data scheme, use an Export or a BigQuery query. Use FIND only when you need live Amazon data that the warehouse does not have yet. One standard Export costs 2 AI Tokens. One integrated BigQuery query costs 0.2 AI Tokens. Compare the total cost of repeated FIND Actions with one Export or query.

See Subscription & Pricing.

What are the available Actions?

Browse every Action type in the Actions explorer. For each Action it shows the access mode, which accounts can run it, item limits, the result, and the JSON Schema of its details. Guides for Action groups, such as budget rules or AMC audiences, are in the same explorer, next to their Actions.

Before you plan an inbound shipment or a listing change, check FBA eligibility and listing restrictions. Call those checks yourself. A listing write does not run them.

AI agents can read the same list as Markdown (opens in a new tab) or JSON (opens in a new tab).

These guides cover specific workflows:

• Actions: FBA eligibility for FBA eligibility and listing restriction checks
• Actions: FBA inbound for inbound shipments to Amazon fulfillment centers
• Actions: External Fulfillment for Seller Flex, Easy Ship and Self Delivery orders
• Actions: Listing images for listing images on create and update

How long does an Action take to complete?

DataDoe runs the Action on Amazon within 15 minutes of the Action starting.

Seller Central and Vendor Central listing changes may take 5 minutes to a few hours for Amazon to process. Amazon Ads changes are processed in real time.

FBA inbound shipments

See the FBA inbound shipment guide for live plans, packing, placement, transport, documents, tracking and receiving reads. These Action types start disabled.

Buy Shipping labels

From 1 November 2026, a business-to-consumer item shipped from outside the European Union into the European Union needs product identifiers. The United Kingdom counts as outside the European Union. A shipment inside the European Union does not.

Amazon adds the ASIN. You supply a manufacturer part number or a model number for each item. If the item has neither, use its barcode. Add an EAN, GTIN, UPC, ISBN, or ISSN when you have one. Do not invent identifiers or placeholders.

1. Get rates with AMAZON_ORDERS_GET_SHIPPING_RATES. A rate that needs more inputs stays available.
2. Load that rate's schema with AMAZON_ORDERS_GET_SHIPPING_ADDITIONAL_INPUTS, using the same requestToken and rateId. The token expires in about 10 minutes.
3. Buy the label with AMAZON_ORDERS_CREATE_SHIPMENT. Set requiresAdditionalInputs to true and send additionalInputs in the form the schema describes, including plain text when the schema asks for text. DataDoe does not buy the label when those values are missing or do not match.
4. Leave both fields out when the rate does not need them.

The same steps are in the Actions explorer, in the Buy Shipping group.

External Fulfillment shipping

See the External Fulfillment shipping guide for Seller Flex, Easy Ship and Self Delivery shipments, packages, invoices and labels. These Actions are separate from Buy Shipping, FBA inbound, Multi-Channel Fulfillment (MCF) and Vendor Direct Fulfillment. They start disabled.