Every Action your AI agents can run on Amazon.

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. A delete dry run checks the SKU list and does not call Amazon.

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.

AMAZON_LISTINGS_DELETE deletes listings by SKU for Seller Central and Vendor Central. Send skus. DataDoe submits a JSON listings feed. Each message uses operationType DELETE and does not include a product type or attributes.

dryRun checks the SKU list and does not call Amazon. Amazon's delete operation has no validation preview, so there is no verify Action.

Deleting a parent SKU removes that parent listing and its relationships to child listings. The child listings remain. Amazon does not change whether buyers can purchase them.

Vendor Central requests require vendorCode. Seller Central requests must not include vendorCode. DataDoe rejects duplicate SKUs in one request.

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.

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.

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.

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.

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}
Copy code

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}
Copy code

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. These FIND Actions count as 1 item per call, so a longer ID list in that one filter does not add AI Tokens. Reads that count each identifier, such as listing lookups, cost less when the identifiers are in one Action.

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.

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.

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.

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.

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.

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.

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}
Copy code

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}
Copy code

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.

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.

DataDoe stores existing budget rules, including rules created in the Amazon Ads console, in amazon_ads_budget_rules. Campaign attachments for Sponsored Products, Sponsored Brands, and Sponsored Display are in amazon_ads_budget_rule_campaigns. On the daily campaign and placement tables, join ad_campaign_applicable_budget_rule_id to budget_rule_id. ad_campaign_applicable_budget_rule_name matches budget_rule_name.

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.type is DAILY or WEEKLY for Sponsored Products, Sponsored Brands and Sponsored Display. A weekly schedule needs daysOfWeek, such as ["SATURDAY", "SUNDAY"]. A daily schedule does not accept daysOfWeek. To pause or resume a rule and leave its schedule unchanged, send ruleId and ruleState only. 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}
Copy code

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}
Copy code

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}
Copy code

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}
Copy code

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 message includes Amazon's message for each failed item.

Amazon retired the budgetRules/budgetHistory endpoints for all three ad products on 31 August 2023 and lists no replacement in its API deprecations notice. 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.

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}
Copy code

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}
Copy code

To pause the rule for every associated Campaign:

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

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.

Eligibility: Sponsored Products advertisers (sellers and vendors). Requires Ads permission advertiser_campaign_edit or advertiser_campaign_view. Source: Sponsored Products API reference. 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}
Copy code

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.

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}
Copy code

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}
Copy code

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}
Copy code

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.

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.

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
• 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

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.

These four Actions use Amazon's Communications Preferences API, 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}
Copy code

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}
Copy code

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}
Copy code

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.

These are Amazon recommendations. Find, apply, and status Actions use a Partner Network account ID saved on the Amazon Ads connection.

• AMAZON_ADS_PARTNER_OPPORTUNITIES_FIND returns one catalog page, not the recommendation rows
• read recommendation rows from amazon_ads_partner_opportunities after the daily sync
• AMAZON_ADS_PARTNER_RECOMMENDATIONS_APPLY sends 1 to 100 recommendation IDs from one account-team opportunity
• dry run does not call Amazon, and HTTP 202 means Amazon accepted the request
• HTTP 202 does not mean the change is complete
• AMAZON_ADS_PARTNER_RECOMMENDATION_STATUS_FIND reads status for 1 to 500 IDs and does not apply them again

See Amazon Ads Partner Opportunities for setup, the nine families, and why a table can be empty.