Skip to main content

Create Rule

POST 

/api/advertising/rules

Creates an automation rule. Rules propose changes on their cron schedule; in suggest mode every run produces change sets that must be approved before anything reaches the ad platform.

Required scope: advertising:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Requires the advertising.manage permission and the Advertising Manager feature.

Body fields:

  • name (required, string, max 255)
  • rule_type (required): bid_to_target_poas, budget_pacing, harvest_search_terms, negate_search_terms, dayparting, placement_adjust or custom.
  • platform (optional): amazon_ads, ebay, google_ads, walmart_connect, meta_ads, tiktok_ads. Null runs on every platform. dayparting and placement_adjust need Amazon Marketing Stream data and accept only amazon_ads (or null).
  • mode (optional, default suggest): suggest (proposals become change sets awaiting approval) or auto (applied automatically). Setting auto additionally requires the advertising.approve permission (403 otherwise).
  • status (optional, default active): active or paused.
  • schedule (optional, cron expression, max 100 chars). Defaults to 15 * * * * for budget_pacing and 0 6 * * * for every other type. An invalid cron returns 422 on schedule.
  • scope (optional object, only these keys): ad_account_ids[] (existing ad account IDs), campaign_ids[] (existing campaign IDs), campaign_name_pattern (string), campaign_types[] (campaign type values such as amazon_sp, ebay_general, google_pmax), product_ids[] (existing product IDs). An empty scope covers every selected ad account of the rule's platform.
  • conditions (optional object; which keys apply depends on rule_type):
    • lookback_days 1-90, min_clicks 1-10000, min_orders 1-1000
    • target_poas 1.0-20 (POAS below 1.0 is below break-even and is rejected), target_margin_pts 0-100
    • max_bid_change_pct 1-100, budget_step_pct 1-100, budget_cutoff_day_pct 10-100, underspend_pct 1-100, max_budget > 0, k 1-20
    • harvest / negate: match_type (exact|phrase), level (campaign|ad_group), bid_multiplier 0.5-3, negate_in_source (boolean), destination_ad_group_id (existing ad group ID)
    • dayparting object: min_days 28-120, min_multiplier 0.5-1, max_multiplier 1-1.5, cell_prior_clicks, hour_prior_clicks
    • custom rules: entity (target|item|ad_group|campaign), match (all|any), clauses[] (max 20) each with metric, op and numeric/boolean value. Metrics: impressions, clicks, spend, sales, orders, units, ctr, cpc, cvr, acos, roas, poas, bid, budget, plus SKU.io inventory inputs cover_days, available, inbound_within_lead_time, days_to_next_inbound, forecast_daily, break_even_acos, unit_contribution, aged_days, buy_box_owned, poas_7d, poas_30d. Operators: >, >=, <, <, =, !=.
  • actions (optional object, custom rules): type (set_bid_pct, set_bid, set_budget_pct, set_budget, pause, enable) and value (numeric; required for the set_* actions).
  • caps_override (optional object): max_bid_change_pct 1-100 and max_budget > 0, overriding the account guardrail caps for this rule.

A custom rule must have at least one clause and an action.

Returns 201 with the created rule.

Request​

Responses​

Created

Response Headers
    Content-Type