Skip to main content

Run Budget Allocation

POST 

/api/advertising/budget-plans/:plan/allocate

Starts the budget allocator for the plan as a queued background job and returns its tracked job ID immediately. The allocator spreads the remaining daily target across the plan's live, budgeted campaigns (excluding constraints.exclude_campaign_ids), respecting the plan's constraints.

Required scope: advertising:write

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

Body: dry_run (optional boolean, default true). A dry run only computes the proposed allocation; dry_run: false produces real campaign budget changes. Poll the tracked job for progress and the outcome.

A run is forced to a preview (result dry_run: true, nothing sent, with the reason in notes) when the plan is not active, when the plan is not for the current month, when the plan's allocation_mode is manual, or when an exchange rate is missing for the plan currency or an account currency.

The tracked job's results carry the allocation: ad_budget_plan_id, dry_run, daily_target, current_total, proposed_total, expected_contribution_change (tenant currency), campaigns_considered, infeasible, notes, change_set_ids (one per ad account when budgets were submitted) and lines. Each line: campaign_id, campaign_name, ad_account_id, platform, currency_code, before and after (daily budget in the account's currency), before_in_tenant_currency and after_in_tenant_currency (the same budgets in the tenant currency, for totals across accounts), marginal_before, marginal_after, elasticity, expected_contribution_change, constraints, reason.

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