Update Guardrail Policy
PUT/api/advertising/guardrail-policies/:policy
Updates a guardrail policy's name, mode and settings. By default the settings you send are merged into the existing ones (deep merge); send replace_settings: true to replace them entirely. event_freezes, when sent, always replaces the list. A policy's scope cannot change (scope_type and scope_id are rejected). Tenant-scoped policies are always kept complete with the built-in defaults.
advertising:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Switching a policy to auto requires the advertising.approve permission (otherwise 403) and a dry run within the last 7 days of the exact settings being enabled (otherwise 422 on mode): changing the thresholds in the same request, or editing a broader policy this one inherits from after the dry run, invalidates it.
A policy already in auto cannot have its thresholds or actions edited in place (422 on mode; 403 without advertising.approve): save the new settings in suggest mode, run a dry run, then switch it back to auto. Renaming it, switching it out of auto, or editing only event_freezes is allowed.
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.
Body fields: name (optional, string, max 255), mode (optional: off, monitor, suggest, auto), replace_settings (optional boolean), plus the settings sections below.
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).
Requires the advertising.manage permission (and advertising.approve for the auto cases above). Personal access tokens need the advertising:write scope.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
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
Not Found
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.