Skip to main content

Create Guardrail Policy

POST 

/api/advertising/guardrail-policies

Creates a guardrail policy for a scope. Only one policy may exist per scope. A new policy cannot start in auto mode: save it in monitor or suggest, run Run Guardrail Policy Dry Run, then switch it with Update Guardrail Policy. mode defaults to monitor. Returns 201 with the policy.

Required scope: advertising:write

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

Body fields:

  • name (required, string, max 255).
  • scope_type (required): tenant, platform, ad_account, campaign, brand, product.
  • scope_id (string matching [A-Za-z0-9_-]{1,100}): required for every scope except tenant (ignored there). A platform value for platform, otherwise the record ID; it must exist.
  • mode (optional): off, monitor, suggest (auto is refused on create).
  • replace_settings (optional boolean): only meaningful on update.

Settings sections (each optional; only the keys you send are stored, unknown keys are dropped):

  • low_cover: enabled (boolean), throttle_cover_days, pause_cover_days, resume_cover_days (integers 1 to 365; resume must be above pause, throttle must not be below pause), throttle_bid_pct, throttle_budget_pct (integers -90 to 0), count_inbound_within_lead_time (boolean).
  • stockout: enabled.
  • delivery_promise: enabled, max_delivery_days (1 to 60), consecutive_checks (1 to 24).
  • acos: enabled, lookback_days (1 to 30), consecutive_days (1 to 30), min_clicks (0 to 100000), margin_buffer_pts (0 to 50), action (alert or throttle_to_target).
  • ebay_ad_rate_cap: enabled, buffer_pts (0 to 50).
  • overstock: enabled, cover_days_above (1 to 1000), aged_days_above (1 to 2000), acos_headroom_pts (0 to 100), ramp_bid_pct (1 to 100).
  • allocate_scarce_stock (boolean).
  • event_freezes (array, max 50): each name (required, max 100), from and to (required, m/d/Y, to on or after from), allow_critical (optional boolean, default true). Sending event_freezes replaces the policy's list.

Defaults for anything a policy does not set come from less specific policies, then the built-in defaults: low cover throttle 21 / pause 14 / resume 21 days, bid -30%, budget -20%; delivery promise off (4 days, 2 checks); ACoS 7-day lookback, 7 consecutive days, 20 clicks minimum, action alert; eBay ad-rate buffer 2 points; overstock off (120 cover days, 180 aged days, 10 points headroom, +15% bid).

Inheritance gates. Settings merge field by field from the tenant policy down to the most specific one, and the most specific policy's mode is in force. A write that changes the thresholds or actions an auto policy inherits (an auto product policy that takes its low-cover thresholds from this account policy, for example) is refused, because the auto policy would run settings no dry run replayed: 403 without the advertising.approve permission, otherwise 422 on mode naming the affected policies. Switch them to suggest, save this change, run a dry run, then switch them back to auto. Event freezes are exempt: they only hold changes back.

Effective low-cover band. The low-cover thresholds must stay coherent on the effective settings (this policy merged over the broader ones it inherits from, and every narrower policy that inherits from it), checked separately for each platform / account / campaign / brand combination a product can resolve under: resume above pause, and pause < throttle < resume. A violation on this policy returns 422 on low_cover.resume_cover_days or low_cover.throttle_cover_days; a violation it causes in a narrower policy returns 422 on low_cover.

Requires the advertising.manage permission (and advertising.approve when the new policy changes settings an auto policy inherits). Personal access tokens need the advertising:write scope.

Request​

Responses​

Created

Response Headers
    Content-Type