Skip to main content

Update Ad Portfolio Budget

PUT 

/api/advertising/portfolios/:portfolio/budget

Sets a new budget cap on an Amazon Ads portfolio by submitting a manual change set with one set_budget line. Nothing reaches Amazon until the change set is approved (Approve Change Set); it then goes through the account's automation caps and the drift check (a cap changed on Amazon since the proposal is skipped, never overwritten) and can be undone.

Required scope: advertising:write

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

The cap is in the ad account's currency and applies over the portfolio's budget policy period: per calendar month for monthly_recurring, or over the portfolio's date range for date_range. An uncapped portfolio (no_cap) gets a monthly cap. estimated_daily_spend_delta counts the cap as its daily equivalent (a monthly cap over 30.4 days).

Body fields

  • budget (required, number): the new cap, > 0 and ≤ 100,000,000.
  • dry_run (optional, boolean, default false): when true, returns a simulated change set with the before/after cap and any caps breached, and saves nothing to the platform. Send a dry run first to preview, then the same body without it.
  • reason (optional, string, ≤ 1000 chars): recorded on the change set and its line.
  • idempotency_key (optional, string, ≤ 80 chars): resubmitting with the same key returns the original change set instead of creating a duplicate. The Idempotency-Key header is accepted as an alternative.

Returns 201 with the new change set (status pending_approval), or 200 for a dry run or an idempotent replay. Returns 404 for an unknown portfolio and 422 when the budget is missing or not greater than zero, or the portfolio's ad account cannot accept the change. Only portfolios with an id in List Ad Portfolios (synced from Amazon) can be edited.

Requires the advertising.manage permission.

Also requires the advertising-manager feature (Advertising Manager plan); without it the endpoint returns 404.

Request​

Responses​

OK

Response Headers
    Content-Type