Skip to main content

Update Budget Plan

PUT 

/api/advertising/budget-plans/:plan

Replaces a budget plan's settings. Send the full plan: the same required fields as create apply.

Required scope: advertising:write

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

Body fields:

  • name (required, string, max 255).
  • month (required): the plan month as m/Y (e.g. 11/2026) or any date in the month as m/d/Y; stored as the first day of the month.
  • scope_type (required): tenant (all selected ad accounts), brand, platform or ad_account.
  • scope_id (required unless scope_type is tenant, ignored for tenant): a brand ID or ad account ID (numeric), or a platform value (amazon_ads, ebay, google_ads, walmart_connect, meta_ads, tiktok_ads).
  • amount (required, number > 0): the monthly budget.
  • currency_code (required, 3-letter ISO code). Pacing converts it to the tenant currency.
  • allocation_mode (optional, default manual): manual, suggest (allocator proposes campaign budget changes) or auto (allocator applies them). auto needs the advertising.approve permission, because it writes platform budgets without a reviewer (otherwise 403); saving a plan in manual or suggest does not.
  • status (optional, default active): draft, active or archived.
  • constraints (optional object) used by the allocator: daily_change_cap_pct (0-100), min_budget (>= 0), max_budget (> 0, nullable), learning_days (integer 0-60), campaign_limits (object keyed by campaign ID, each with optional min >= 0 and max > 0), exclude_campaign_ids (array of campaign IDs the allocator must not touch).

Only one non-archived plan may exist per scope and month; a duplicate returns 422 on month.

Requires the advertising.manage permission.

Available only when the tenant has both the advertising and advertising-manager features enabled; otherwise every route here returns 404.

Request​

Responses​

OK

Response Headers
    Content-Type