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.
advertising:writeGrant 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 exampletarget_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 theIdempotency-Keyheader: retrying with the same key returns the first revision with status200; a new revision returns201.
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
- 200
- 201
- 401
- 403
- 404
- 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.
Not Found
Response Headers
Conflict
Response Headers
Unprocessable Content
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.