Create Budget Plan
POST/api/advertising/budget-plans
Creates a monthly budget plan. Returns 201 with the plan. Creating a plan does not change any campaign budgets by itself; use Run Budget Allocation to spread it.
advertising:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body fields:
name(required, string, max 255).month(required): the plan month asm/Y(e.g.11/2026) or any date in the month asm/d/Y; stored as the first day of the month.scope_type(required):tenant(all selected ad accounts),brand,platformorad_account.scope_id(required unlessscope_typeistenant, ignored fortenant): 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, defaultmanual):manual,suggest(allocator proposes campaign budget changes) orauto(allocator applies them).autoneeds theadvertising.approvepermission, because it writes platform budgets without a reviewer (otherwise403); saving a plan inmanualorsuggestdoes not.status(optional, defaultactive):draft,activeorarchived.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 optionalmin>= 0 andmax> 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
- 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.