Skip to main content

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.

Required scope: advertising:write

Grant 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 marked superseded (its pending lines skipped, any open approval request cancelled), so it can never be approved alongside its replacement. Not allowed with dry_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. A portfolio line (Amazon Ads portfolios, by the id from List Ad Portfolios) supports set_budget only: after.budget is 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_state needs after.state, set_bid needs after.bid, set_budget needs after.budget, set_ad_rate needs after.ad_rate (otherwise 422 on changes.<n>.after.<key>). A line may only set the field its operation writes: a set_bid line that also sends after.state is refused (422 on changes); 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 in before, or the line is refused with 422.
    • 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): the line_key of 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 as depends_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​

OK

Response Headers
    Content-Type