Create Change Set
POST/api/advertising/change-sets
Creates a manual change set for one ad account from a list of changes. Nothing is sent to the ad platform by this call: a manual set always waits for approval (status pending_approval, expiring after 48 hours by default) and must be approved with Approve Change Set. A dry run (dry_run: true) is simulated only and ends in status simulated.
advertising:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Each change is checked against the account's automation caps; any breached caps are listed in caps_breached. A proposal larger than the max_changes_per_set cap is split into several sets and the first one is returned. If no line can be applied (held, unsupported or no longer on the platform) the set is created in status failed.
Idempotency: send an Idempotency-Key header (or the idempotency_key body field, up to 80 characters). Retrying with the same key returns the original set with status 200 instead of creating another; a new set returns 201.
Body fields:
ad_account_id(required, integer): the ad account the changes belong to. Every referenced entity must belong to this account.dry_run(optional, boolean, default false): simulate only.summary(optional, string, max 200): defaults to e.g. "2 manual changes on Acme US".reason(optional, string, max 2000).idempotency_key(optional, string, max 80).supersedes_change_set_id(optional, integer, nullable): makes this set an edited copy of a set that is still pending approval on the same ad account. In the same transaction the original is markedsuperseded(its pending linesskipped, any open approval request cancelled), so it can never be approved alongside its replacement. Not allowed withdry_run: true. If no line of the new set can apply, the original is left pending. To edit only values of an existing set, Revise Change Set is simpler.changes(required, array of 1 to 5000):entity_type(required):campaign,ad_group,item,target,feed_product,product_set,portfolio. Aportfolioline (Amazon Ads portfolios, by theidfrom List Ad Portfolios) supportsset_budgetonly:after.budgetis the new cap over the portfolio's budget period (per calendar month, or over its date range), in the account currency; its spend delta counts the cap as a daily equivalent.entity_id(integer, nullable): the SKU.io ID of the entity; required by every operation that edits an existing entity.external_id(string, nullable, max 150): the platform's ID for the entity.operation(required):set_state,set_bid,set_budget,set_ad_rate,set_target_value,set_roi_target,add_negative,add_target,add_item,remove_item,set_feed_pause,set_custom_label,create_campaign,archive_campaign,set_placement_modifier,set_bid_schedule.after(required, object with at least one key): the new value(s). Validated keys:state(enabled,paused,archived),bid(> 0),budget(> 0),ad_rate(> 0, up to 100, a percentage). Other operation-specific keys (target_value, campaign-creation fields, ...) are kept as sent. The scalar edits must carry their own key:set_stateneedsafter.state,set_bidneedsafter.bid,set_budgetneedsafter.budget,set_ad_rateneedsafter.ad_rate(otherwise422onchanges.<n>.after.<key>). A line may only set the field its operation writes: aset_bidline that also sendsafter.stateis refused (422onchanges); propose each field as its own line.before(optional, object): the value(s) you expect the entity to have now; used by the drift check at apply time. When omitted, SKU.io reads the current value from its copy of the entity. If SKU.io has no current value for a field the line changes (state,bid,budget,ad_rate,target_value,roi_target,paused,custom_label,in_product_set), send it inbefore, or the line is refused with422.reason(optional, string, max 1000).product_id(optional, integer): the SKU.io product the line concerns.line_key(optional, string, max 80): a name for this line, unique within the request, that later lines can depend on.depends_on_key(optional, string, max 80): theline_keyof an earlier line this one needs applied first (for example a negative keyword after the keyword it was harvested into, or a bid on a target the set creates). The line runs after that line, takes the platform ID it created when it has none of its own, fails if that line does not apply, and cannot be approved without it. In the response it appears asdepends_on_change_id.
Returns 409 when supersedes_change_set_id names a set that is no longer pending approval (already approved, applied, rejected or expired) or that another edit already replaced (error key superseded, naming the replacement). Returns 422 when that set no longer exists or is on another ad account, with dry_run: true, when two lines share a line_key, or when a depends_on_key is not the line_key of an earlier line.
Errors that depend on the account's state (platform not connected for writes, write access pending platform approval, an entity on another account, an unknown entity) return 422 with the reason.
Requires the advertising.manage permission. Personal access tokens need the advertising:write scope.
Request
Responses
- 200
- 201
- 401
- 403
- 409
- 422
- 429
OK
Response Headers
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Conflict
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.