Skip to main content

Revise Change Set

POST 

/api/advertising/change-sets/:changeSet/revise

Edits the values of a change set that is pending approval, on the server, and returns the revised copy. You send only the new values; the lines are not re-described. The revised set keeps the original's source, source reference, signal and the holds its lines would create. Its caps, estimated spend delta and approval tier are evaluated again, and it waits for approval (status pending_approval); nothing is sent to the ad platform.

Required scope: advertising:write

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

In the same transaction the original is marked superseded: its pending lines are skipped, any open approval request for it is cancelled, and approving or rejecting it afterwards returns 409. The revision's supersedes_change_set_id is the original's ID, and the original's superseded_by_change_set_id is the revision's.

Edits change values only: an edited line keeps its entity, operation and baseline (before), and can change only the after fields it already sets (a set_bid line takes a new bid, not a state). A line that depends on another pending line (depends_on_change_id, such as a negative keyword after its harvested keyword) keeps that link in the revision: keep both lines, or neither.

Body fields:

  • lines (required, array of 1 to 5000): the edited lines.
    • lines.*.id (required, integer, distinct): the ID of a pending line of this set.
    • lines.*.after (required, object with at least one key): the new values. Validated keys: state (enabled, paused, archived), bid (> 0), budget (> 0), ad_rate (> 0, up to 100, a percentage). Any other key the line already sets (for example target_value) is taken as sent.
  • line_ids (optional, array of distinct integers, at least 1 when present): the pending lines the revision keeps. Omit it (or send null) to keep every pending line. Every edited line must be kept; pending lines left out are not carried into the revision.
  • idempotency_key (optional, string, max 80), or the Idempotency-Key header: retrying with the same key returns the first revision with status 200; a new revision returns 201.

Returns 409 (error key superseded) when the set was already replaced by another edit; the message names the replacement to decide on. Returns 422 when the set is no longer pending approval or has expired (error key expired), when a listed line is not a pending line of this set, when an edited line is not in line_ids, when an edit sets a field the line does not already set, when a kept line depends on a line that is left out, or when a field fails validation.

Requires the advertising.approve permission. Personal access tokens need the advertising:write scope.

Request​

Responses​

OK

Response Headers
    Content-Type