The automation language

Rules are written in a small, readable language built for Amazon Ads: loop over an entity, check conditions on its metrics, call actions. The editor has syntax highlighting, autocomplete, inline error checking, and a built-in reference; every run is recorded and revertible.

The basic shape

Bodies are indented two spaces. Keywords, entities, fields, and functions are case-insensitive.

Entities you can loop over

Hop to related entities with a dot: keyword.campaign, searchTerm.adGroup, campaign.portfolio, campaign.placement. Related objects can be named: LET campaign = keyword.campaign.

Inside the row you already have: child loops

A FOR EACH written inside a block reads what is inside the row it is standing on. Where the outer loop says which table to read, the child loop names a parent object — and the rows it hands back are ordinary rows, with the same fields, metrics and actions they have in a top-level loop.

This is what lets one rule cross two dimensions. "A campaign for every proven search term and every proven ASIN in its ad group" is one loop inside another:

# ALLOW CREATION
FOR EACH searchTerm IN LAST 90 DAYS:
  IF searchTerm.orders > 25 AND searchTerm.acos < 20%:
    FOR EACH product IN searchTerm.adGroup OVER LAST 30 DAYS:
      IF product.orders > 5:
        LET name = CONCAT("MD, ", product.asin, ", ", searchTerm.searchTerm)
        LET camp = createCampaign(name, budget: $10, targeting: "manual", portfolio: createPortfolio("MerchDash"))
        LET ag = camp.createAdGroup(name, $0.25)
        ag.addAsin(product.asin)
        ag.createKeyword(searchTerm.searchTerm, "exact", $0.25)
    END
END

A child loop iterates what is in the ad group right now, from the same snapshot the Campaigns pages read — not only what Amazon reported activity for. Metrics on those rows are read for the window in force, so an ASIN that never delivered reads zero rather than disappearing.

Across every campaign: accumulated reports

A keyword row is one keyword in one ad group, and a product row is one ad in one campaign. So a keyword that looks acceptable in each of ten campaigns, but has quietly spent $40 with no orders across all of them, is invisible to an ordinary loop. An accumulated report is the rollup the Accumulated tabs show, built for the run and iterated like any other entity:

CREATE ACCUMULATED KEYWORD REPORT IN LAST 60 DAYS

FOR EACH accumulated_keyword:
  IF accumulated_keyword.spend >= $40 AND accumulated_keyword.orders = 0:
    accumulated_keyword.pauseEverywhere()
    accumulated_keyword.note("{spend:money} across {campaigns} campaigns, no orders")
END

The same works for ASINs with CREATE ACCUMULATED ASIN REPORT and FOR EACH accumulated_asin. The report exists only for that run — nothing appears under Reports.

Fields. Every metric, plus keywordText, matchType, asin, sku, the counts campaigns / adGroups / keywords / ads, their live and paused halves in full — live_keywords / paused_keywords, live_ads / paused_ads, live_campaigns / paused_campaigns, live_ad_groups / paused_ad_groups, and keyword_state / asin_state — ENABLED when anything can still deliver, PAUSED when nothing can. Both spellings work: live_keywords and liveKeywords. An ASIN row also splits its ads by ad product: sp_ads is the Sponsored Products share of ads, and sb_ads counts the Sponsored Brands ads whose creative features the ASIN right now — a snapshot that is not part of ads and carries no metrics of its own, because Amazon publishes no per-ASIN reporting for Sponsored Brands (why).

Accumulated rows carry one metric the per-entity loops don’t: cpo, cost per order (spend ÷ orders). Like every ratio it has no value when the denominator is zero, so a row with no orders is skipped by a numeric comparison rather than matching as infinity.

Actions say how far they reach. One row is many real entities, so pause() does not apply to it — use pauseEverywhere(), setBidEverywhere(v) or negateEverywhere([match]). Each acts on every instance that delivered in the report's window and is still enabled, and each writes ordinary History entries you can revert.

Acting on a proven ASIN's bids

An ASIN has no bid. A bid lives on the keywords and targets that advertise it — which is why there is no setBidEverywhere() for an ASIN, and never will be. An ASIN row therefore has child loops: they iterate what that ASIN delivered through inside the report's timeframe, as ordinary rows you can read and act on. Everything it ran in is handed back, so the report decides which ASINs and the rule decides what to touch.

CREATE ACCUMULATED ASIN REPORT IN LAST 60 DAYS

FOR EACH accumulated_asin:
  IF accumulated_asin.orders > 10 AND accumulated_asin.cpo < $2.50:
    FOR EACH keyword IN accumulated_asin:
      IF keyword.state = "ENABLED":
        keyword.setBid(MIN($1.50, keyword.bid * 1.10))
        keyword.note("ASIN {accumulated_asin.asin} proven across campaigns")
    END
END

The report decides which ASINs; the child loop does the acting. keyword, target and adGroup all work this way. Note the placeholder: inside the child loop a bare {asin} would ask the keyword for an ASIN it does not have, so name the outer row — {accumulated_asin.asin}.

Metrics & fields

Read any metric off an item over the loop's window (or an inline one):

Plus settings and identity per entity: bid, bidInherited, budget, state, name, matchType, keywordText, searchTerm, asin, adType, targetingType, biddingStrategy, portfolioName, adGroupCount, the owning campaign's campaignName / campaignState (on ad groups, keywords, targets, search terms and ASINs — no relation hop needed), placement percentages (top_of_search, product_pages, rest_of_search) — whose own names are placementTopPct / placementProductPagePct / placementRestOfSearchPct, so either spelling reads, and recency fields days_since_bid_change / days_since_budget_change / days_since_placement_change. Friendly aliases work everywhere (daily_budget, purchases, conversion_rate, tos, …) — the editor autocompletes them all.

Which kind of target is this? Use target.targeting. It reads exactly one of "close match", "loose match", "substitutes", "complements" (the four Sponsored Products auto-targeting clauses) or "product" for manual product and category targeting, and nothing at all when the row does not say — normal for Sponsored Brands and Display targets. It is what you want for a per-clause rule, such as a lower maximum bid on complements than on close match. target.targetingClause is the same field under its original name and still works.

targetingMode is not that field: it reads "AUTO" or "MANUAL" — whether the target sits in an auto or a manual campaign — and never names the clause. target.targetingMode = "SUBSTITUTES" therefore matches nothing, and the editor refuses it rather than letting the rule run to no effect. Any time you mean a clause, write target.targeting.

Has this search term already been negated? searchTerm.negated is TRUE when an exact negative already covers that term in its ad group or campaign — counting both the negatives a sync read back from Amazon (so negatives you or another tool created in the console are seen too) and the ones MerchDash itself applied. It is the gate every negation recipe filters on, and the reason a negation rule doesn't re-propose the same term every run:

Less common fields

Everything above covers most rules. These are real too, and read the same way:

Time ranges

The window after FOR EACH is optional and defaults to the last 30 settled days. Any metric read can carry its own inline window: keyword.clicks IN LAST 7 DAYS.

Conditions & operators

Settings read as they are now. Time ranges apply to metrics only. Fields such as bid, budget, biddingStrategy, state, and the placement percentages always return their current value — an inline window on one (keyword.bid IN LAST 30 DAYS) does not look up what it used to be. To react to a change, use DAYS_SINCE_CHANGE("bid") / LAST_CHANGE("budget") — and DAYS_SINCE_CHANGE("top of search") for a placement.

Placement adjustment cool-downs

A Sponsored Products campaign carries three placement bid adjustments — top of search, product pages, rest of search — and campaign.setPlacementBid() changes them. Because a placement adjustment needs several days of traffic before its effect is visible, a rule that adjusts one should refuse to adjust it again straight away; otherwise the next run judges the same data and moves it a second time.

Ask how long ago it changed the same way you would for a bid or a budget:

The count covers every placement change MerchDash applied — from a rule and from a bulk edit on the Campaigns page alike — and is Infinity for a campaign it has never adjusted, so a first run still matches. Placement recency is campaign-level and Sponsored Products only; on a keyword, target or ad group it reads Infinity. The percentages themselves stay read-only: campaign.placement.top_of_search reads, setPlacementBid() writes.

Entities with no impressions

Amazon only reports a keyword, target or ASIN on days it actually showed, so one with zero impressions in the window has no report row at all. A FOR EACH normally iterates what was reported — which is where its metrics come from — so those silent entities used to be invisible to every rule. On a quiet portfolio that can be most of it.

MerchDash decides this per loop, with no syntax on your part. A silent row reads as zero impressions, clicks, cost, orders and sales (ACOS, ROAS, CTR and CVR are undefined, so every comparison against them is false).

When they are included

First, the condition has to be able to match one at all. keyword.impressions < 1000 can; keyword.clicks > 7 never can, so that loop keeps reading reported rows only and stays exactly as fast as before.

Then it depends on what the rule does:

• setBid and note — always included. Raising the bid on something nobody has seen yet is the entire point.
• pause, archive, enable, setState, addNegative, createKeyword, createTarget, addAsin — only when the rule tests impressions. Write impressions = 0 or impressions < 50 and it reaches them.
• createPortfolio, createCampaign, createAdGroup — never. They create something, so a block that calls one reads reported rows only, even though it is written inside a LET rather than as an action.

The reason for that last rule is that clicks = 0 and orders = 0 describe something that ran and failed — that is how almost every “pause the losers” rule is written. Something that never ran is a different thing, and only an impressions test says so. Without that distinction, a rule meant to pause a handful of duds would pause every idle keyword and ASIN in the account.

FOR EACH product IN LAST 60 DAYS:
  IF product.impressions = 0:            # reaches ASINs that never ran
    product.pause()
END

FOR EACH keyword IN LAST 30 DAYS:
  IF keyword.clicks = 0:                 # only keywords that DID run
    keyword.pause()
END

What is covered

Keywords, targets and ASINs work as described. Campaigns and ad groups have always been read from the full stored list, so one with no traffic already appears with zeros. Search terms cannot be: a search nobody typed does not exist.

Archived entities are never included, whichever rule you write.

Forcing it

Override the decision with a comment above the loop — it applies to every FOR EACH below it, until another one overrides it:

# INCLUDE ZERO IMPRESSIONS
FOR EACH keyword IN LAST 30 DAYS:
  IF keyword.campaign.portfolioName = "Winter":
    keyword.setBid(keyword.bid + $0.02)
END

# EXCLUDE ZERO IMPRESSIONS forces the opposite, which is worth doing on a very large account when you only care about entities that actually ran.

Looking things up by name

A rule loops over one kind of item, and every relation points upward — a keyword knows its campaign, but a campaign does not list its keywords. The lookups fill that in: they fetch a specific campaign, ad group or portfolio by name from anywhere in a rule, and read what is inside it.

Three things worth knowing. A lookup that finds nothing answers NONE, so test it with IS NONE / IS NOT NONE — and calling an action on NONE stops the run rather than quietly doing nothing, because a rule with a stale name would otherwise look like a rule that simply had nothing to do. A name matching two items also stops the run and names both IDs: names are not unique on Amazon, so the rule cannot guess which one you meant — use the _ID form. And a lookup inside a loop costs one read no matter how many rows the loop has, so it is safe to write it there.

Paused & archived campaigns

The mirror image of the section above. A campaign you paused part-way through the window still reported for the days before that, so everything inside it — keywords, targets, ad groups, ASINs, search terms — is still in the data a FOR EACH reads. Rewriting bids there costs you part of the run's change limit and can never win an auction.

Skip paused and archived campaigns in Profile → General (on by default) leaves them out. Two kinds of loop keep their paused campaigns automatically, so the setting can't turn a rule into a no-op:

• A loop that can run enable() or setState() — a reactivation rule has to be able to see what is off.
• A loop that reads campaign state itself: campaign.state, keyword.campaignState, target.campaign.state — or the same hop bound to a variable first, LET campaign = keyword.campaign then campaign.state. You have already said what you want.

Archived campaigns are skipped either way — with the setting on, with it off, and for both of the loops above. Amazon rejects every write into an archived campaign, so those rows can only become failures in your history. Turning the setting off brings back paused campaigns, nothing more.

Force it per rule with a comment above the loop, scoped exactly like the zero-impressions directive:

# INCLUDE PAUSED CAMPAIGNS
FOR EACH keyword IN LAST 30 DAYS:
  IF keyword.acos > 45%:                 # prepare bids before relaunching
    keyword.setBid(keyword.bid * 0.9)
END

# EXCLUDE PAUSED CAMPAIGNS forces the skip on, even when the setting is off and even for a loop that would otherwise exempt itself.

Actions

Functions

Building a campaign

A rule can build the whole structure — portfolio, campaign, ad group, ASINs, targets and keywords — in one pass:

The constant names inside the loop are deliberate. However many search terms match, that is one campaign and one ad group: each name is a single request, proposed once and reviewed once, with the ASINs and clauses batched onto one row each.

Two things to know

A rule has to ask. # ALLOW CREATION on a line of its own is what lets a rule build campaigns and ad groups; without it the rule will not save. Every other action a rule can take moves a number on something you already chose to run — a new campaign is new spend, so it is the one capability a rule cannot start using because somebody edited it. (createPortfolio does not need it: a portfolio holds no budget.)

Everything is created live. The campaign, the ad group, the ASINs, the clauses and the keywords all arrive ENABLED, so a structure a rule builds serves as soon as you approve the run — there is no second run and nothing left to switch on. To build a piece switched off instead, add state: "paused" to any create verb:

"enabled" and "paused" are the only two values, and each create verb takes its own — a live campaign whose keywords go in paused is a perfectly good thing to ask for. One thing still belongs to a later run: a rule cannot enable, rename or re-budget a campaign on the run that creates it, because there is nothing there yet to change, and those lines are refused when the rule is saved. Everything settable at creation is a named argument instead.

A fuller example