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.
advertising:writeGrant 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 excepttenant(ignored there). A platform value forplatform, otherwise the record ID; it must exist.mode(optional):off,monitor,suggest(autois 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(alertorthrottle_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): eachname(required, max 100),fromandto(required,m/d/Y,toon or afterfrom),allow_critical(optional boolean, default true). Sendingevent_freezesreplaces 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
- 201
- 401
- 403
- 422
- 429
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.