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. See Subscription & Pricing for Action costs.

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

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.

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 is enabled for the Organization (enabled), and the start tool (actions_start) with actions_details_schema_get. When enabled is false, an Organization owner 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.
5. Start the Action with the same tool and dryRun=false.
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 share usage charges and Action history. 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) and startTool (actions_start) alongside the payload schema.

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

You can also get all your past Actions 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/start 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.
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 all your past Actions using the GET /actions resource.

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

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.

What are the available Actions?

W in brackets means write operations, R in brackets means read operations.

Both are followed by the availability for Sellers and Vendors.

Amazon - Listings Actions

AMAZON_LISTINGS_COMPETITIVE_SUMMARY_FIND reads the live Amazon response. Competitive Summaries and Competitive Offer Promotions are separate opt-in warehouse snapshots. Amazon does not accept a promotions value in includedData. Promotions arrive inside featuredBuyingOptions and lowestPricedOffers.

Request:

1{
2    "includedData": [
3        "featuredBuyingOptions",
4        "lowestPricedOffers",
5        "referencePrices",
6        "similarItems"
7    ],
8    "competitiveSummaries": [
9        {
10            "asin": "B000000001",
11            "lowestPricedOffersInputs": [{ "itemCondition": "New", "offerType": "Consumer" }]
12        }
13    ]
14}

A successful item keeps the Amazon body. Featured promotions are at response.featuredBuyingOptions[].segmentedFeaturedOffers[].promotions[]. Lowest-priced promotions are at response.lowestPricedOffers[].offers[].promotions[].

Amazon - A+ Content Actions

Amazon - Vendor purchase order Actions

Vendor accounts only. Purchase order lists, purchase order status, and shipment details stay in the warehouse tables. These Actions submit and retrieve the live Retail Procurement and Direct Fulfillment operations. Customer invoices, invoice submission, and container labels are not Actions. Creating Direct Fulfillment shipping labels, retrieving those labels, and retrieving packing slips returns the end customer's name and address. Those three Actions require PII access, the same entitlement as Vendor Direct Fulfillment Orders PII.

Amazon - Orders Actions

AMAZON_ORDERS_FIND and AMAZON_ORDERS_GET_METRICS are a live preview of current Amazon data. For large volumes and long-term analysis, use Exports or a direct BigQuery integration. Those also refresh during the day.

Seller Central only. Messaging writes call getMessagingActionsForOrder first and send only when Amazon lists that action for the order. Text is plain text in the buyer locale from AMAZON_ORDERS_MESSAGING_ATTRIBUTES_GET. Attachments are DataDoe file UUIDs in the ORDER_MESSAGE_FILES group, uploaded to Amazon through the Uploads API. Amazon's published examples mention CreateAmazonMotors and createNegativeFeedbackRemoval, but Messaging v1 has no callable operation for them, so they are not Actions. Negative-feedback removal is not a product-review change. Review solicitations stay on AMAZON_ORDERS_SOLICITATION_FEEDBACK_SEND.

Amazon - FBA Actions

Amazon - MCF Actions

MCF order lifecycle uses Fulfillment Outbound v2026-07-04. Return actions use v2020-07-01 because Amazon has not ported returns to v2026.

India payment on delivery

Payment on delivery is available only for a connected India Seller account shipping to an address in India. Prepaid Multi-Channel Fulfillment (MCF) orders stay the default. Omit paymentOnDelivery, or set it to false, and do not send a line-item service price.

Preview the option with AMAZON_MCF_ORDERS_PREVIEW before you create an order. Set includePaymentOnDelivery to true. Amazon reports delivery.paymentOnDelivery as ENABLED or DISABLED on each offer, and includes any constraints. The preview does not create an order, collect payment, or complete delivery. DataDoe rejects a destination outside India. It also rejects a Seller connection that is not the India marketplace.

Create the order with AMAZON_MCF_ORDERS_ADD. Set paymentOnDelivery to true and send a price in Indian rupees (INR) on every line item, in perUnitServicePrice. Each line keeps its own amount. The amount must be greater than zero. DataDoe rejects a missing price and a price sent without paymentOnDelivery set to true. It also rejects a currency other than INR and a destination whose countryCode is not IN. It does not fill in a missing price or currency. A Seller connection that is not the India marketplace is rejected as well.

Amazon accepting the order means Amazon accepted the fulfillment request. Acceptance does not mean the customer paid, or that delivery is complete.

AMAZON_MCF_FEATURES_MARKETPLACE_FIND returns these same rules and does not call Amazon. REST POST /api/v1/actions and MCP actions_start use the same fields.

For example, preview payment on delivery:

1{
2    "type": "AMAZON_MCF_ORDERS_PREVIEW",
3    "sellerOrVendorId": "your-seller-id",
4    "dryRun": true,
5    "details": {
6        "includePaymentOnDelivery": true,
7        "destination": {
8            "deliveryAddress": {
9                "name": "Mary Major",
10                "addressLine1": "Connaught Place",
11                "city": "New Delhi",
12                "postalCode": "110001",
13                "countryCode": "IN"
14            }
15        },
16        "lineItems": [
17            {
18                "product": { "productIdentifier": { "amazonSku": "SKU-1" } },
19                "amount": { "unit": "EACHES", "value": "1" }
20            }
21        ]
22    }
23}

Create the order with AMAZON_MCF_ORDERS_ADD and these details. Send a separate INR price for each line:

1{
2    "orders": [
3        {
4            "orderId": "india-order-1",
5            "paymentOnDelivery": true,
6            "fulfillmentConfiguration": {
7                "serviceLevel": { "serviceTiers": ["STANDARD"] }
8            },
9            "destination": {
10                "deliveryAddress": {
11                    "name": "Mary Major",
12                    "addressLine1": "Connaught Place",
13                    "city": "New Delhi",
14                    "postalCode": "110001",
15                    "countryCode": "IN"
16                }
17            },
18            "lineItems": [
19                {
20                    "lineItemId": "item-1",
21                    "product": { "productIdentifier": { "amazonSku": "SKU-1" } },
22                    "amount": { "unit": "EACHES", "value": "1" },
23                    "fulfillmentConfiguration": {
24                        "services": {
25                            "delivery": {
26                                "paymentOnDelivery": {
27                                    "perUnitServicePrice": {
28                                        "currencyCode": "INR",
29                                        "amount": "14.99"
30                                    }
31                                }
32                            }
33                        }
34                    }
35                },
36                {
37                    "lineItemId": "item-2",
38                    "product": { "productIdentifier": { "amazonSku": "SKU-2" } },
39                    "amount": { "unit": "EACHES", "value": "2" },
40                    "fulfillmentConfiguration": {
41                        "services": {
42                            "delivery": {
43                                "paymentOnDelivery": {
44                                    "perUnitServicePrice": {
45                                        "currencyCode": "INR",
46                                        "amount": "20.00"
47                                    }
48                                }
49                            }
50                        }
51                    }
52                }
53            ]
54        }
55    ]
56}

Amazon Tracking API Actions

The following Actions are available for Amazon Seller Central and Vendor Central:

Amazon Ads Actions

Amazon Ads Action models and flows follow the structure shown in the Amazon Ads API documentation (opens in a new tab).

The following Actions are available for Amazon Ads:

Upload and find creative assets

Creative assets are images and videos in Amazon's Creative Asset Library. Upload a file first, then start AMAZON_ADS_ASSETS_ADD. The action stays in processing until Amazon finishes spec checks.

Eligibility follows Amazon's published coverage:

• Console launch on 2021-07-15: vendors, sellers, and KDP authors in the US, CA, and MX. Creative assets (opens in a new tab)
• Sponsored Display and Ads API expansion on 2022-04-19: vendors and registered sellers in the US, CA, MX, BR, DE, ES, FR, IT, NL, UK, AE, AU, IN, and JP. Sponsored Display creative assets (opens in a new tab)

Create the file with POST /files in group AD_ASSETS (PNG, JPG, MP4, or MOV, up to 500MB), then PUT the bytes to the returned uploadUrl within 30 minutes. DataDoe then handles Amazon's own upload URL, which expires after 15 minutes, while the action runs. For video, MCP files_create should use uploadMode: UPLOAD_URL, which returns { file, uploadUrl } and does not require contentBase64. Inline MCP upload stays limited to the smaller image size.

AMAZON_ADS_ASSETS_ADD uploads each file and registers it. Images can take up to 1 hour and videos up to 6 hours before the action completes. The result lists each file in items with its assetId, assetVersion, status, and spec-check issues. A failed action keeps items too, so assets Amazon already registered stay usable. Sellers must set brandEntityId (look it up with AMAZON_ADS_BRANDS_FIND). Vendors may omit it. AMAZON_ADS_ASSETS_FIND looks up assets by id or returns one search page plus nextToken.

DSP creative-asset upload is not available until DSP actions ship. Do not send adProduct: AMAZON_DSP.

Bids before launching a campaign

Eligibility: Sponsored Products advertisers (sellers and vendors). Requires Ads permission advertiser_campaign_edit or advertiser_campaign_view. Source: Sponsored Products API reference (opens in a new tab). POST /sp/targets/bid/recommendations is available in marketplaces where Sponsored Products is available. Amazon returns HTTP 422 for an unsupported marketplace or an ineligible product. DataDoe reports that error on the item and does not invent a bid.

AMAZON_ADS_SP_BID_RECOMMENDATIONS_FIND accepts two item modes in details.bidRecommendations. An existing ad group sends adGroupId and targetings. A new ad group sends asins, targetings, and bidding, with no adGroupId. Supply exactly one mode. bidding is rejected on an existing ad group because that ad group uses its campaign's strategy.

asins is 1 to 50 unique uppercase 10-character ASINs. targetings reuses the existing expression list, including KEYWORD_EXACT_MATCH, KEYWORD_PHRASE_MATCH, and KEYWORD_BROAD_MATCH. Keyword expressions need a nonempty value. bidding.strategy is LEGACY_FOR_SALES (dynamic bids, down only), AUTO_FOR_SALES (dynamic bids, up and down), MANUAL (fixed bids), or RULE_BASED. Optional bidding.adjustments uses PLACEMENT_TOP, PLACEMENT_REST_OF_SEARCH, and PLACEMENT_PRODUCT_PAGE, at most one of each, with an integer percentage from 0 to 900.

1{
2    "type": "AMAZON_ADS_SP_BID_RECOMMENDATIONS_FIND",
3    "sellerOrVendorId": "your-seller-or-vendor-id",
4    "dryRun": true,
5    "details": {
6        "bidRecommendations": [
7            {
8                "asins": ["B012345678"],
9                "targetings": [
10                    { "type": "KEYWORD_EXACT_MATCH", "value": "stainless steel bottle" },
11                    { "type": "KEYWORD_PHRASE_MATCH", "value": "water bottle" }
12                ],
13                "bidding": { "strategy": "AUTO_FOR_SALES" }
14            }
15        ]
16    }
17}

The ASIN above is illustrative. Use an eligible product from an authorized Ads account. A multi-ASIN item is one recommendation group. Results and errors keep the original index and the input ASINs. DataDoe does not add campaign or ad group ids for this mode. Suggested bids can differ from the Ads console because strategy, placement settings, timing, and product eligibility all affect them.

AMAZON_ADS_SP_TARGET_RECOMMENDATIONS_FIND ASIN items accept optional biddingStrategy with the same four values. Omit it to keep Amazon's default, LEGACY_FOR_SALES. Ad group items reject biddingStrategy. An explicit strategy is sent only on keyword recommendation version 5. That version is available in US, CA, BR, MX, UK, DE, FR, ES, IN, IT, NL, AE, SA, TR, EG, BE, SE, PL, JP, AU, and SG. Elsewhere the item fails with an unsupported-version error. DataDoe does not drop the strategy and retry an older version.

Currency units are not the same on every response. On keyword recommendation version 5, bidInfo[].bid is in minor currency units, such as cents. The spec does not state a unit for keyword bidInfo[].suggestedBid or for bid-recommendation suggestedBid. DataDoe returns Amazon's numbers unchanged and does not convert them. Compare a live response with the console before treating those fields as cents.

Manage budget rules

Budget rule Actions use separate types for Sponsored Products (SP), Sponsored Brands (SB), and Sponsored Display (SD). A SCHEDULE rule increases a Campaign's daily budget during a date range or an Amazon event. A PERFORMANCE rule increases it when the Campaign meets a metric threshold. Create a rule, then associate its returned ruleId with one or more Campaigns of the same ad product.

Send rule definitions in details.budgetRules when creating rules. To update a rule, send its ruleId and either ruleState, ruleDetails, or both. Include only the fields you want to change in ruleDetails. Use ruleState: "PAUSED" to stop a rule from being evaluated, or "ACTIVE" to enable it again.

Each rule definition needs name, ruleType, budgetIncreaseBy, and duration. Use budgetIncreaseBy.type: "PERCENT" with a positive value. Provide exactly one of duration.dateRangeTypeRuleDuration and duration.eventTypeRuleDuration. Dates use YYYYMMDD; the end date is inclusive and must be on or after the start date. An event duration uses an Amazon eventId. Unknown fields and read-only fields are rejected.

Optional recurrence supports DAILY for Sponsored Products and DAILY or WEEKLY for Sponsored Brands and Sponsored Display. Weekly recurrence uses daysOfWeek, such as ["SATURDAY", "SUNDAY"]. An optional intraDaySchedule contains one time window with startTime and endTime in HH:mm:ss format; the end time must be later than the start time.

Performance rules also need performanceMeasureCondition with metricName, comparisonOperator, and threshold. Sponsored Products and Sponsored Display accept ACOS, CTR, CVR, and ROAS; Sponsored Brands accepts IS, NTB, and ROAS. Schedule rules omit performanceMeasureCondition.

For example, create a Sponsored Products schedule rule through POST /api/v1/actions:

1{
2    "type": "AMAZON_ADS_SP_BUDGET_RULES_ADD",
3    "sellerOrVendorId": "your-seller-or-vendor-id",
4    "dryRun": true,
5    "details": {
6        "budgetRules": [
7            {
8                "name": "Holiday budget increase",
9                "ruleType": "SCHEDULE",
10                "budgetIncreaseBy": { "type": "PERCENT", "value": 20 },
11                "duration": {
12                    "dateRangeTypeRuleDuration": {
13                        "startDate": "20261201",
14                        "endDate": "20261231"
15                    }
16                },
17                "recurrence": { "type": "DAILY" }
18            }
19        ]
20    }
21}

After creating the rule in live mode, associate the returned ID using AMAZON_ADS_SP_BUDGET_RULES_ASSOCIATE and these details:

1{
2    "associations": [
3        {
4            "campaignId": "123456789012345",
5            "budgetRuleIds": ["your-budget-rule-id"]
6        }
7    ]
8}

To pause the rule, use the matching BUDGET_RULES_UPDATE Action with these details:

1{
2    "budgetRules": [{ "ruleId": "your-budget-rule-id", "ruleState": "PAUSED" }]
3}

Association limits count the total rule IDs across all Campaigns in the Action: 25 through the API or 10 through MCP. A batch may have both successful and failed items; inspect the outcome for each item in the Action result.

Use AMAZON_ADS_SP_BUDGET_RULES_REMOVE, AMAZON_ADS_SB_BUDGET_RULES_REMOVE, or AMAZON_ADS_SD_BUDGET_RULES_REMOVE to remove a rule from a Campaign. This removes that association and keeps the rule available for other Campaigns. For example, send these details:

1{
2    "removals": [
3        {
4            "campaignId": "123456789012345",
5            "budgetRuleId": "your-budget-rule-id"
6        }
7    ]
8}

DataDoe spaces requests to each budget rule endpoint at one request per second for each Ads profile. Amazon applies dynamic limits. For a throttled request, DataDoe honors Amazon's Retry-After header when present and retries up to twice within the 30-second request deadline. If the request still fails, the Action result records the failed items.

Audit budget rule executions

Amazon retired the budgetRules/budgetHistory endpoints for all three ad products on 31 August 2023 and lists no replacement in its API deprecations notice (opens in a new tab). Budget rule execution history is unavailable through Actions. The Action history records DataDoe requests to create, update, associate, or remove rules from Campaigns; it does not record Amazon's daily rule evaluations.

Manage scheduled bid increases

Sponsored Products scheduled bid rules increase bids during a clock-time window. Dayparting means raising bids during set hours, and these Actions are useful for that. Amazon applies the schedule. DataDoe does not send a bid update each time the window starts or ends.

Create a rule with AMAZON_ADS_SP_BID_RULES_ADD, then attach the returned optimization rule ID with AMAZON_ADS_SP_BID_RULES_ASSOCIATE. Creating a rule does not attach it to a Campaign. These Actions are separate from budget rules and from Sponsored Products ROAS optimization rules.

Each created rule needs ruleName, bidIncreasePercent, duration, and recurrence. bidIncreasePercent is a whole number from 1 to 100. DataDoe sends Amazon an increase of that percentage. Optional status is ENABLED or PAUSED. When status is omitted, DataDoe sends ENABLED.

recurrence.type is DAILY or WEEKLY. A weekly schedule needs daysOfWeek. A daily schedule does not accept daysOfWeek. Optional timesOfDay is one window. startTime and endTime are hours in HH:00 in the Amazon Ads profile timezone. endTime may be 24:00 and must be later than startTime. duration.startTime and optional duration.endTime are absolute ISO-8601 timestamps with a timezone, such as 2026-12-01T00:00:00Z. When you change a schedule, send duration and recurrence together. An update loads the current rule and sends Amazon the complete rule, including the name, percentage, and schedule you did not change.

There is no Action to unlink a rule from one Campaign or to delete a rule. Pause or resume a rule with AMAZON_ADS_SP_BID_RULES_UPDATE and status. Pausing stops that rule for every Campaign that uses it. It does not remove the association.

Search with AMAZON_ADS_SP_BID_RULES_FIND. Send either optimizationRuleIds or one campaignId, not both. A Campaign search returns only scheduled bid rules for that Campaign. There is no search that lists every rule. pageSize is from 1 to 100, and DataDoe sends it to Amazon as maxResults. When the result includes nextToken, send it again with the same filters.

For example, increase bids by 20 percent on Saturday and Sunday from 17:00 to 21:00 through POST /api/v1/actions:

1{
2    "type": "AMAZON_ADS_SP_BID_RULES_ADD",
3    "sellerOrVendorId": "your-seller-or-vendor-id",
4    "dryRun": true,
5    "details": {
6        "bidRules": [
7            {
8                "ruleName": "Weekend evening increase",
9                "bidIncreasePercent": 20,
10                "duration": {
11                    "startTime": "2026-12-01T00:00:00Z",
12                    "endTime": "2026-12-31T23:59:59Z"
13                },
14                "recurrence": {
15                    "type": "WEEKLY",
16                    "daysOfWeek": ["SATURDAY", "SUNDAY"],
17                    "timesOfDay": [{ "startTime": "17:00", "endTime": "21:00" }]
18                }
19            }
20        ]
21    }
22}

After creating the rule in live mode, associate the returned ID:

1{
2    "associations": [
3        {
4            "campaignId": "123456789012345",
5            "optimizationRuleIds": ["your-optimization-rule-id"]
6        }
7    ]
8}

To pause the rule for every associated Campaign:

1{
2    "bidRules": [{ "optimizationRuleId": "your-optimization-rule-id", "status": "PAUSED" }]
3}

Create and update batches allow 25 rules through the API or 10 through MCP. Association limits count the campaign-rule pairs in the Action. A batch may contain both successful and failed items. Amazon can reject a rule when the profile or Campaign is not eligible; the Action result includes Amazon's message. DataDoe spaces scheduled bid rule requests at one request per second for each Ads profile, separately from budget rule requests.

Create AMC audiences for Sponsored Ads

AMC audiences are groups of shoppers that you select with SQL in Amazon Marketing Cloud, for example shoppers who added a product to the cart but did not buy it. You can use them in Sponsored Products and Sponsored Brands to increase bids for these shoppers, and in Sponsored Display to target them. DSP audiences are not supported.

AMC audience Actions run in the AMC instance of the Seller or Vendor, so enable AMC for it first. Without AMC, the Actions return HTTP 412 with a message that explains what is missing.

• AMAZON_ADS_AMC_AUDIENCES_ADD creates a rule-based audience from SQL. The final SELECT must return only user_id, and the tables must be AMC audience tables, whose names end in _for_audiences (for example conversions_for_audiences or sponsored_ads_traffic_for_audiences). Amazon fails an audience with fewer than 2,000 shoppers, so check the size first with an AMC query on the matching table without _for_audiences.
• AMAZON_ADS_AMC_LOOKALIKE_AUDIENCES_ADD creates a lookalike audience from a seed query of 500 to 500,000 shoppers. lookalikeAudienceExpectedReach sets how broad it is, from MOST_SIMILAR (about 0.5 to 1 million shoppers) to MOST_BROAD (about 3 to 10 million).
• timeWindowStart and timeWindowEnd are UTC date and times ending in Z. With timeWindowRelative: true, Amazon moves the window forward on each refresh.

Amazon builds an audience in the background, and DataDoe does not attach it to campaigns later on its own. Your AI agent or integration takes these steps:

1. Create the audience. The result includes its audienceExecutionId.
2. Check it with AMAZON_ADS_AMC_AUDIENCES_FIND every 15 to 30 minutes until status is SUCCEEDED. When it is FAILED, statusReason explains why. Fix the audience with AMAZON_ADS_AMC_AUDIENCES_UPDATE.
3. Amazon lists a SUCCEEDED audience in Sponsored Ads after about 24 to 48 hours. Get its Sponsored Ads audienceId with AMAZON_ADS_TARGETABLE_AUDIENCES_FIND, using the ad product and the audience name. When the audience is not listed yet, try again later.
4. Attach the audienceId: in Sponsored Products and Sponsored Brands with audienceBidAdjustments in AMAZON_ADS_CAMPAIGNS_UPDATE, or in Sponsored Display with an AUDIENCE target in AMAZON_ADS_TARGETS_ADD (audienceTarget.audienceId.defaultValue).

AMAZON_ADS_AMC_AUDIENCES_UPDATE works only for FAILED audiences. It can change the SQL and the time window; the name, description, and lookalike reach stay as they are. AMAZON_ADS_AMC_AUDIENCES_REMOVE deletes FAILED or SUCCEEDED audiences, and Amazon also removes them from Sponsored Ads.

For example, create an audience of shoppers who added a product to the cart but did not buy it after that (the query from Amazon's AMC instructional queries), through POST /api/v1/actions:

1{
2    "type": "AMAZON_ADS_AMC_AUDIENCES_ADD",
3    "sellerOrVendorId": "your-seller-or-vendor-id",
4    "dryRun": true,
5    "details": {
6        "audiences": [
7            {
8                "audienceName": "Cart abandoners 30 days",
9                "sql": "WITH purchase AS (SELECT user_id, MAX(event_dt_utc) AS purchase_dt_max FROM conversions_for_audiences WHERE event_subtype = 'order' GROUP BY 1), atc AS (SELECT user_id, MAX(event_dt_utc) AS atc_dt_max FROM conversions_for_audiences WHERE event_subtype = 'shoppingCart' GROUP BY 1) SELECT atc.user_id FROM atc LEFT JOIN purchase ON atc.user_id = purchase.user_id WHERE atc_dt_max > purchase_dt_max OR purchase_dt_max IS NULL",
10                "timeWindowStart": "2026-09-20T00:00:00Z",
11                "timeWindowEnd": "2026-10-19T00:00:00Z",
12                "timeWindowRelative": true
13            }
14        ]
15    }
16}

When the audience is listed in Sponsored Ads, find its audienceId with AMAZON_ADS_TARGETABLE_AUDIENCES_FIND:

1{
2    "adProduct": "SPONSORED_PRODUCTS",
3    "audienceName": "Cart abandoners 30 days"
4}

Then increase bids for it by 30 percent in a Sponsored Products campaign with AMAZON_ADS_CAMPAIGNS_UPDATE:

1{
2    "campaigns": [
3        {
4            "campaignId": "123456789012345",
5            "adProduct": "SPONSORED_PRODUCTS",
6            "audienceBidAdjustments": [{ "audienceId": "your-audience-id", "percentage": 30 }]
7        }
8    ]
9}

One Action creates, updates, or deletes up to 10 audiences through the API and 5 through MCP. Creating or updating an audience costs 5 AI Tokens per audience (currently promotional 0). Finding and deleting audiences is free. See Subscription and pricing.

Manage communication contacts and preferences (Amazon open beta)

These four Actions use Amazon's Communications Preferences API (opens in a new tab), which Amazon released as an open beta on 1 October 2026. Amazon may change it before general availability. The connected Amazon Ads user needs the account view permission for FIND and the account edit permission for ADD and UPDATE. These differ from the campaign permissions other Ads Actions use. Without them, the Action fails with a permission message. Communication preferences belong to the Amazon Ads profile of the Seller or Vendor: in DataDoe's tests, two marketplaces on the same Amazon Ads account had separate preferences with different IDs. Run FIND and UPDATE for each Seller or Vendor whose preferences you want to change. Amazon does not document whether contacts apply to one profile or to the whole Amazon Ads account.

AMAZON_ADS_COMMUNICATION_CONTACTS_ADD registers account support contacts. Amazon cannot edit or delete a contact through the API, so run the Action with dryRun first. Each contact has a channel (EMAIL or PHONE) and a contactAddress with exactly one of emailAddress or phoneNumber. Phone numbers use E.164, such as +442071234567. contactPurpose defaults to ACCOUNT_SUPPORT, the only purpose Amazon accepts. Optional timeZone accepts only Amazon's list of 44 IANA zones; zones such as Europe/Warsaw or Europe/Berlin are rejected. DataDoe first lists the existing contacts and skips an address that already exists, returning it with alreadyExists: true. Other contacts are sent one per Amazon request. If Amazon lists more than 500 contacts on a channel, DataDoe cannot check them all, so the Action fails before adding any contact.

AMAZON_ADS_COMMUNICATION_CONTACTS_FIND and AMAZON_ADS_COMMUNICATION_PREFERENCES_FIND take one channel, plus optional maxResults (1 to 100) and nextToken. Contacts use EMAIL or PHONE. Preferences use EMAIL or UI (in-app messages).

Category IDs are not fixed values. Get communicationPreferenceId and categoryId from AMAZON_ADS_COMMUNICATION_PREFERENCES_FIND, then update with AMAZON_ADS_COMMUNICATION_PREFERENCES_UPDATE. communicationsEnabled is required. When it is true, send at least one categoryPreferences entry; Amazon would otherwise subscribe the account to every category. Send communicationsEnabled: false to stop every communication on that channel. DataDoe checks the IDs against the current preferences and sends Amazon the full category list: the current subscriptions with your changes applied. Categories you omit keep their current state. Each result item contains Amazon's updated communicationPreference and the previousCommunicationPreference.

For example, list email preferences:

1{
2    "type": "AMAZON_ADS_COMMUNICATION_PREFERENCES_FIND",
3    "sellerOrVendorId": "your-seller-or-vendor-id",
4    "details": { "channel": "EMAIL" }
5}

Then unsubscribe from one category and keep the channel enabled:

1{
2    "type": "AMAZON_ADS_COMMUNICATION_PREFERENCES_UPDATE",
3    "sellerOrVendorId": "your-seller-or-vendor-id",
4    "dryRun": true,
5    "details": {
6        "communicationPreferences": [
7            {
8                "communicationPreferenceId": "your-communication-preference-id",
9                "communicationsEnabled": true,
10                "categoryPreferences": [
11                    { "categoryId": "your-category-id", "isCategorySubscribed": false }
12                ]
13            }
14        ]
15    }
16}

Add an email contact for account support:

1{
2    "type": "AMAZON_ADS_COMMUNICATION_CONTACTS_ADD",
3    "sellerOrVendorId": "your-seller-or-vendor-id",
4    "dryRun": true,
5    "details": {
6        "communicationContacts": [
7            {
8                "channel": "EMAIL",
9                "contactAddress": { "emailAddress": "ads-team@example.com" },
10                "preferredContact": true,
11                "timeZone": "Europe/London"
12            }
13        ]
14    }
15}

ADD accepts 5 contacts and UPDATE 2 preferences, through the API and MCP. DataDoe masks email addresses and phone numbers in its internal Amazon Ads call logs. The Action details and result keep the full values.

Find with many IDs

Amazon accepts up to 100 IDs in one ID filter (campaignIdFilter, adGroupIdFilter, adIdFilter, targetIdFilter, portfolioIdFilter, adAssociationIdFilter). In AMAZON_ADS_CAMPAIGNS_FIND, AMAZON_ADS_AD_GROUPS_FIND, AMAZON_ADS_TARGETS_FIND, AMAZON_ADS_ADS_FIND, and AMAZON_ADS_AD_ASSOCIATIONS_FIND, one ID filter can have more IDs. DataDoe queries the IDs in groups of 100 and returns up to maxResults results (100 by default). If there are more results, the response has a nextToken. Send it with the same query to get the next page. Only one ID filter per request can have more than 100 IDs. Split other large ID filters into several Actions.

Sponsored Brands campaigns

AMAZON_ADS_CAMPAIGNS_ADD for SPONSORED_BRANDS uses the brand entity ID (ENTITY…) as brandId: AMAZON_ADS_BRANDS_FIND.brandEntityId, the same value as AMAZON_ADS_CAMPAIGNS_FIND.brandId. Do not send the A… brandId from brands FIND. brandId is required for sellers and optional for Vendor Central accounts. Use kpi: "CLICKS", bidStrategy: "MANUAL" (or omit it), and exactly one DAILY or LIFETIME budget. Placement adjustments support HOME_PAGE, PRODUCT_PAGE, and REST_OF_SEARCH only.

Manual vs theme targeting is locked when the campaign is created. On AMAZON_ADS_CAMPAIGNS_ADD, omit smartDefault or set it to "MANUAL". DataDoe sends manual targeting, so the campaign can take product and keyword targets. Set smartDefault to "TARGETING" to use theme targets. Theme targeting blocks product targets. Send one value, not a list.

Do not set smartDefault on AMAZON_ADS_CAMPAIGNS_UPDATE. Campaigns that already exist keep their targeting. To change manual vs theme targeting, create a new campaign.

Sponsored Brands ads

AMAZON_ADS_ADS_ADD for SPONSORED_BRANDS (adType: "COMPONENT") supports two formats: product collection (creative.componentCreative.productCollectionSettings) and video (creative.componentCreative.productVideoSettings). Other Sponsored Brands formats are not supported. Every ad needs adGroupId, name, and state.

• Product collection: created as an Amazon Manual Collection ad. brand (at most 30 characters), at most one brandLogos entry, at most one headline of at most 32 characters (sent as the ad title; Amazon generates one when omitted), and 3–10 product ASINs. landingPage can be STORE (with a Store landingPageUrl) or ASIN_LIST (a Store URL is used as the Store page; otherwise the page lists the product ASINs, and landingPageAsins, if sent, must match them). customImages, CUSTOM_URL landing pages, and creativePropertiesToOptimize are not supported.
• Video: exactly one videos entry and one product ASIN. The ad lands on the product detail page.

AMAZON_ADS_ADS_UPDATE for Sponsored Brands ads changes only name and state; creative changes are not supported. Targets can be added to a Sponsored Brands ad group only after it has at least one ad.

Sponsored Display ad groups

Set the bid optimization of a Sponsored Display ad group with optimization.goalSettings.kpi on AMAZON_ADS_AD_GROUPS_ADD:

optimization accepts only bidStrategy, budgetSettings, and goalSettings.kpi; other keys (for example bidOptimization) are rejected. Amazon may ignore a changed KPI on AMAZON_ADS_AD_GROUPS_UPDATE, so check it with AMAZON_ADS_AD_GROUPS_FIND. If it did not change, create a new ad group with the right KPI. Optimization cannot be set on Sponsored Display campaigns.

Sponsored Display ads

AMAZON_ADS_ADS_ADD for SPONSORED_DISPLAY (adType: "COMPONENT") creates product ads. Each ad advertises exactly one product: creative.sku, creative.asin, or creative.componentCreative.responsiveEcommerceSettings.products[0] with productId and productIdType. Send one ad item per product. Amazon builds the creative from the product detail page, so custom creative settings (logos, headlines, images, assetBasedCreativeSettings) are not supported. Sellers advertise SKUs; for Seller Central accounts an ASIN is resolved to a SKU from synced listings data. Vendors advertise ASINs. Do not send marketplaces, marketplaceScope, marketplaceConfigurations, or product marketplaceSettings; the marketplace comes from the Ads profile.

Mixed ad products in add, update, and remove actions

Amazon does not accept campaigns, ad groups, ads, or targets from different ad products in one write request. Add, update, and remove actions can still mix them: DataDoe splits the items by adProduct and sends one request per product. If one of these requests fails, only its items fail. Add items always carry adProduct. On update and remove, if an item has no adProduct, DataDoe looks it up by ID; an ID that is not found for the Ads profile fails only that item.

Sponsored Products Auto campaigns

Automatic vs manual targeting is locked when the campaign is created. Use AMAZON_ADS_CAMPAIGNS_ADD with targetingType: "AUTO" (preferred) or autoCreationSettings.autoCreateTargets: true. Then create an ad group and at least one product ad. Amazon creates the four Auto theme targets (Close Match, Loose Match, Substitutes, Complements). List them with AMAZON_ADS_TARGETS_FIND and optionally set bids with AMAZON_ADS_TARGETS_UPDATE or AMAZON_ADS_SP_BID_RECOMMENDATIONS_FIND. Amazon does not allow creating these targets, so AMAZON_ADS_TARGETS_ADD rejects positive THEME targets with these match types.

Do not set targetingType or autoCreationSettings on AMAZON_ADS_CAMPAIGNS_UPDATE. To change Auto vs Manual, create a new campaign.

Negative targeting

Negatives use AMAZON_ADS_TARGETS_ADD with negative: true. Ad-group level uses adGroupId. Campaign level uses campaignId. Do not send a bid on negatives.

Negative keyword:

1{
2    "adProduct": "SPONSORED_PRODUCTS",
3    "state": "ENABLED",
4    "negative": true,
5    "targetType": "KEYWORD",
6    "adGroupId": "217994746792262",
7    "targetDetails": {
8        "keywordTarget": {
9            "keyword": "cheap",
10            "matchType": "EXACT"
11        }
12    }
13}

Negative ASIN:

1{
2    "adProduct": "SPONSORED_PRODUCTS",
3    "state": "ENABLED",
4    "negative": true,
5    "targetType": "PRODUCT",
6    "adGroupId": "217994746792262",
7    "targetDetails": {
8        "productTarget": {
9            "matchType": "PRODUCT_EXACT",
10            "productIdType": "ASIN",
11            "product": { "productId": "B0895LY6F1" }
12        }
13    }
14}

Sponsored Products v3 expression types map to DataDoe as follows:

Amazon's public Sponsored Products v3 expression format is not the DataDoe contract; DataDoe follows Amazon Ads API v1.

Listing validation preview

AMAZON_LISTINGS_CREATE_VERIFY, AMAZON_LISTINGS_UPDATE_VERIFY, AMAZON_LISTINGS_DETAILS_UPDATE_VERIFY, and AMAZON_LISTINGS_PRICING_UPDATE_VERIFY call Amazon Listings Items with mode=VALIDATION_PREVIEW. Each call checks one SKU and returns Amazon status, submission ID, and issues. The preview does not create or change the listing. Amazon validation preview does not accept a merge. DataDoe previews a merge with replace and the same values. The write still sends merge.

VERIFY Actions accept up to five distinct SKUs through the API or MCP. All changes for each SKU are sent together in one Amazon request. Update previews also keep the matching write Action’s total change limit: 5,000 through the API or 50 through MCP.

dryRun is a different check. It validates the DataDoe request and does not submit the change. For create and details updates, dryRun also checks the product-type schema. A pricing dry run checks that schema when the change includes productType. A basic listing update dry run does not fetch it.

To check a listing before a write, run dryRun, then the matching VERIFY Action, then the write Action. Pricing preview is Seller Central only, matching AMAZON_LISTINGS_PRICING_UPDATE.

Audience prices

AMAZON_LISTINGS_PRICING_UPDATE sets the single-unit price for one audience on a Seller Central listing. Omit audience, or set it to ALL, to set the price every buyer pays.

Use B2B for Amazon Business buyers. Use an industry audience, such as B2B_EDUCATION, for business industry pricing (IVP). Amazon documents these audiences for the United States, and from 15 October 2026 also for Canada, the UK, Germany, France, Italy, Spain, and Japan. ALL works in every marketplace.

Industry audiences are available when the seller is enrolled in Amazon Business. Amazon calls this subscription SellingToBusinesses. The audiences a seller can use are on the product-type schema for that seller and marketplace. Load it with AMAZON_LISTINGS_PRODUCT_TYPE_DEFINITION_FIND. Send that product type on the price change. DataDoe checks the audience, price, and quantity discounts against that schema.

A price change merges the selected audience, currency, and marketplace. Other audiences stay as they are. Quantity discounts, price limits, and automated pricing rules stay as they are unless you send a new quantity-discount plan. If Seller Central has an automated pricing rule for that audience, Amazon applies the rule instead of the price you send.

quantityDiscount is for an Amazon Business or industry audience. discountType is percent or fixed. When discountType is percent, 5 means 5% off the single-unit price. When discountType is fixed, value is the unit price buyers pay in the marketplace currency once the order reaches lowerBound. lowerBound is the minimum quantity for that tier. Omit quantityDiscount to leave the current tiers in place.

You can send more than one audience for the same SKU. DataDoe sends them in one price update. Do not repeat the same audience for a SKU.

Read current audience prices from amazon_listings_audience_pricing. One row is one connection, marketplace, SKU, and audience. unit_price is the single-unit price. quantity_discount_tiers lists those tiers. When discount_type is percent, value is the percent off the single-unit price. When discount_type is fixed, value is the unit price.

To check a price before you send it, run dryRun, then AMAZON_LISTINGS_PRICING_UPDATE_VERIFY, then AMAZON_LISTINGS_PRICING_UPDATE. When the change includes productType, dryRun checks the product-type schema. The verify Action asks Amazon to preview the price with replace, because validation preview does not accept merge. It does not change the price. The price update still merges that audience only.

Listing requirements

Each change in AMAZON_LISTINGS_CREATE can include requirements. When you omit it, DataDoe uses LISTING.

Choose one value:

• LISTING creates a full listing, with product data and your offer
• LISTING_OFFER_ONLY adds your offer on an ASIN that already exists in the Amazon catalog
• LISTING_PRODUCT_ONLY sends product data without an offer

A dry run checks attributes against the product type schema for that value. Load the same value with AMAZON_LISTINGS_PRODUCT_TYPE_DEFINITION_FIND and productTypeRequirementsSet.

For LISTING_OFFER_ONLY, send the SKU, condition, price, and fulfillment attributes required by that schema.

Listing images

To set listing images on create or update, upload files to the LISTING_IMAGES group first, then reference file UUIDs in AMAZON_LISTINGS_CREATE or AMAZON_LISTINGS_UPDATE. See Files for upload details and Actions - Manage Images for the full workflow, slot mapping, and MCP and API examples.

A+ Content images

To include images in A+ Content documents, upload files to the APLUS_IMAGES group first, then reference file UUIDs in image components inside AMAZON_APLUS_CONTENT_ADD, AMAZON_APLUS_CONTENT_UPDATE, or AMAZON_APLUS_CONTENT_VALIDATE.

Premium A+ and Brand Story

A+ Content Actions accept Standard (STANDARD_*), Premium (PREMIUM_*), and Brand Story (BRAND_STORY_*) modules. Keep one module family per document:

• Standard and Premium documents use contentType EBC (sellers) or EMC (vendors) and take up to seven modules. Standard documents of vendors take up to five.
• Brand Story documents use contentType BrandStory: exactly one BRAND_STORY_IMAGE_WITH_LOGO background module plus up to 19 cards, for sellers and vendors.

Premium video modules (PREMIUM_VIDEO_TEXT, PREMIUM_HERO_VIDEO, PREMIUM_VIDEO_IMAGE_CAROUSEL) reference a video and its thumbnail by videoMediaId and imageMediaId. Register the pairing with AMAZON_APLUS_MEDIA_ADD: pass the existing video mediaId, its descriptions (one per locale), and a thumbnail image as an APLUS_IMAGES file, an existing media library path, or a mediaId. DataDoe does not upload video files. Amazon can take up to 48 hours to process a video; check its status with AMAZON_APLUS_MEDIA_FIND.

You can send AMAZON_APLUS_CONTENT_FIND output back to AMAZON_APLUS_CONTENT_UPDATE after your changes. Every image needs imageCropSpecification, except catalog images (/images/I/…) that Amazon fills in for ASIN cards.

AMAZON_APLUS_CONTENT_FIND skips documents with premium modules that Amazon SP-API does not expose. Those documents are listed under skipped and do not fail the Action.

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.