completed, or submitted for review that takes hours/days)
Request Schema: creative/sync-creatives-request.json
Response Schema: creative/sync-creatives-response.json
Quick start
Upload creative assets:creatives[].status (e.g., pending_review) on the synchronous success response. When the whole operation is queued (batch ingestion, governance review gating the sync), the response is a submitted envelope with top-level status: "submitted" and a task_id. See Async approval workflow.
In AdCP 3.3, assignments and assignment_operations may assign an existing
pending_review or rejected library creative. Otherwise valid assignments
remain in place through review, rejection, and correction under the same
creative_id; assignment is not authorization to serve. By default eligible
approved assignments start independently. A buyer may instead set a package’s
start_requires_all_creatives_approved: true through control_media_buy to hold its first release for serving. See the
creative start policy for package approval, status, and resubmission rules.
For campaigns with a short launch window, sync the creative into a seller library before booking, wait for review, then assign it to a package. Library approval and package assignment eligibility are separate checks.
Read-after-write visibility
Creatives accepted via a synchronoussync_creatives success response MUST be committed to the creative library before the response is returned. They MUST be immediately visible to subsequent list_creatives calls from the same account and authorized caller, including creatives whose review lifecycle status is processing or pending_review.
Implementations that acknowledge a creative on the synchronous success branch but buffer the library write until a later background commit are not conformant. If the whole sync operation cannot commit before returning, use the submitted task envelope instead; the visibility requirement then applies when the task completes with accepted creatives.
A product can declare a separate creative_policy.review_sla for time to an approved or rejected decision. The applicable creative entry in the buy’s available_actions[] resolves review_sla independently of ingestion timing. See Service commitments for product scope, business calendars, and the rule that an ingestion acknowledgement does not complete review.
Request parameters
Every
creatives[] item in one request MUST have a unique creative_id.
Duplicate IDs make response correlation and write ordering ambiguous, so the
seller rejects the request rather than applying last-write-wins behavior.
Which operations a seller accepts
In AdCP 3.3, a seller lists theassignment_operations it accepts in creative.assignment_operations on get_adcp_capabilities, for example ["assign", "unassign", "replace"].
- The list is exact. The seller accepts every listed operation. It rejects any other with
UNSUPPORTED_FEATURE, witherror.fieldat that operation, and applies nothing, because the request is atomic. - Buyers send only listed operations. Buyers MUST NOT send an operation the seller does not list. When the list is absent from a capabilities response served at 3.3 or later, the seller accepts none, and buyers MUST NOT send
assignment_operationsat all. - Earlier releases. A capabilities response served at 3.2 cannot carry the list, so its absence there declares nothing. A buyer pinned to 3.2 learns what the seller accepts from
UNSUPPORTED_FEATURE. replaceand live updates. A seller that declarescreative.live_updatesMUST listreplace, because swapping in a newcreative_idis how a buyer recovers fromCREATIVE_LIVE_UPDATE_UNSUPPORTED.- Compact buys need
assign. A seller that exposesbuy_productsoraccept_proposaland declarescreative.has_creative_library: trueMUST listassignin a capabilities response served at 3.3 or later, because the compact lifecycle assigns creatives only throughassignment_operations. merge. Listingmergerequirescreative.has_creative_library: trueandcreative.stable_creative_ids: true. The oldercreative.supports_assignment_mergeflag stays for compatibility: when it istrue, the list MUST includemerge, and a seller that listsmergeSHOULD set it. Where the two disagree, the list governs.
sync_creatives assignment_operations only. It says nothing about the deprecated assignments[] shorthand or the creative_assignments rows of create_media_buy and update_media_buy.
Assignment landing pages
The deprecated
assignments[] row does not carry landing_page_url or trackers. The 3.3 betas accepted both there; they are withdrawn from that row before 3.3 GA (adcp#8501), and the row rejects them by name. Neither does a package creative_assignments row on the deprecated create_media_buy or update_media_buy: that row is open, so a seller ignores them there. Send them on an assignment_operations assign.landing_page_url on the assign variant of assignment_operations[] replaces the click-through destination for that one creative on that one package. The library creative does not change. The override applies to every click-through destination for that assignment, including per-state destinations; the seller MUST serve it everywhere it applies or reject the assignment through existing assignment errors, and MUST NOT silently ignore it or apply it partially. This includes clicks embedded in HTML, JavaScript, or a VAST tag that the seller cannot override. The creative’s approval stands; a seller that reviews destinations reviews the assignment, not the creative.
Buyers MUST NOT send the field unless get_adcp_capabilities declares creative.supports_assignment_landing_page: true (default false, requiring has_creative_library: true); an agent without that capability MUST reject the field with UNSUPPORTED_FEATURE. The URL may contain AdCP macros under the same rules as the creative’s own click-through without declarations, including the existing 3.x compatibility behavior. This field introduces no assignment-level macro_declarations; declarations on the original creative assets do not transfer to the override, and neither URL syntax nor this capability proves declared token resolution. Existing governed catalog substitution and encoding rules still apply.
On assign operations, omitting landing_page_url preserves an existing override. To restore inheritance without changing the library creative, atomically unassign then assign the same creative/package without the field; include any weight, placement settings, or assignment trackers that must remain on the new assignment. null is not accepted. Package creative_assignments rows on create_media_buy and update_media_buy carry no landing_page_url, so a complete update_media_buy replacement restores inheritance on every row it supplies; omitting the entire replacement array leaves assignments unchanged.
The unassign/assign reset recreates assignment state. Its assign operation cannot carry rotation_mode, group_id, sequence_position, or structured placement_refs. To retain those controls, send a complete update_media_buy package creative_assignments replacement that keeps every assignment with its rotation, group, and placement settings. The replacement clears assignment trackers and landing_page_url on every row it supplies, so follow it with assign operations that restore the trackers and overrides that should remain; an assign on an existing assignment upserts the settings it carries. The two calls are not atomic, so pause the package first if it must not serve without its assignment trackers or landing-page overrides. Readback URLs are effective destinations, so do not blindly copy them into override fields when reconstructing authored assignment state.
Supporting sellers MUST return the effective serving destination in list_creatives assignments and get_media_buys package creative assignment rows (packages[].creative_approvals[]). Return the override when present, otherwise the creative’s own destination when unique; a macro-bearing destination remains the effective URL template. Omit the scalar when no destination exists or an unoverridden creative has multiple destinations, whose URLs remain in its creative assets. Sellers MUST NOT pick one arbitrarily and present it as applying to every click. Buyers reconcile assignment approval_status separately from the library creative’s status.
After an assignment merge, the buyer creative’s landing page for that package applies: its assignment override when present, otherwise its own click-through. The same serve-or-reject and assignment destination-review rules apply when the merge changes the effective destination; inherited creative approval MUST NOT bypass destination policy. A seller that cannot apply the destination rejects the atomic merge instead of keeping the seller copy’s old destination silently.
After checking the capability and setting an override with an assign operation, the buyer can restore inheritance with this atomic reset. This reset uses existing operations, so its example references the released v3 request schema.
Assignment trackers
In AdCP 3.3, optionaltrackers on the assign variant of assignment_operations[] attaches measurement URLs to one creative on one package. A buyer can reuse a library creative across media buys while giving each assignment its own campaign and package values. The seller fires these trackers in addition to the creative’s own trackers. Changing assignment trackers does not mutate the library creative, its revision, or its approval; any tracker policy review applies to the assignment.
Buyers MUST NOT send trackers unless get_adcp_capabilities declares creative.supports_assignment_trackers: true. This capability defaults to false and requires has_creative_library: true; an unsupported agent MUST reject the field with UNSUPPORTED_FEATURE. It is independent of creative.supports_assignment_landing_page.
Each entry contains event and url, with custom_event_name required and nonempty only when event is custom. Events use the shared pixel_tracker vocabulary and timing. Each URL is invoked as an HTTP GET measurement pixel, without JavaScript execution. Assignment trackers do not carry asset_type, method, or macro_declarations. They are renderer-fired measurement, not advertiser-site conversion tracking; use event sources for the latter.
The seller MUST fire every accepted assignment tracker at its declared event or reject the assignment through existing assignment errors. This includes unknown custom events and events that cannot fire on the assigned format; silent no-op behavior is not permitted. Where a tracker_execution_contract applies, match assignment entries as pixel_tracker with method: "img" and the entry’s event/custom name, respecting its execution actor and firing paths. An unlisted selector in a complete contract rejects the assignment; an undeclared selector does not waive the fire-or-reject requirement. The capability alone does not promise that every format accepts every event.
Assignment trackers and the creative’s own trackers count together against the effective format’s tracker-slot limits, including canonical params.slots[].max and legacy repeatable-group max_count. A tracker slot is a declared slot with asset_type: "pixel_tracker", or one whose asset_group_id is a canonical tracker slot (impression_tracker, click_tracker, viewability_tracker). Each assignment tracker consumes one occurrence in one compatible tracker slot; existing creative assets retain their slot occupancy. A tracker is compatible by event:
impression_trackertakesimpression;click_trackertakesclick;viewability_trackertakes theviewable_*events andaudible_video_complete;- any other
pixel_trackerslot takes any event.
image format, whose tracking model fires trackers through macros, makes no slot-limit claim: the seller does not reject an assignment tracker for lack of a slot. The fire-or-reject rule above still applies, so the seller MUST fire every accepted tracker at its declared event or reject the assignment, for example for an event the format cannot fire. The same rules govern trackers that a replace transfers, counted alongside the replacement creative’s own trackers. Each supplied occurrence fires once per logical event; identical URLs are not deduplicated, including when the same URL also appears in a creative asset.
Tracker URLs use the existing macro-bearing URL rules without declarations, including 3.x compatibility behavior. Declarations on creative assets do not transfer to these URLs. Neither URL syntax nor assignment tracker support guarantees resolution of any particular macro; check the seller’s macro resolution capabilities. Buyers can put their own known buy/package values directly in the URL, avoiding a dependency on seller ID substitution. Readback preserves the accepted templates.
Supplying trackers replaces that assignment’s previous tracker list; it does not append on each upsert or retry. Omission on assign operations preserves the list. To clear it, use the atomic unassign/assign reset recipe, omitting trackers from the new assignment and resupplying other authored settings, including any landing-page override. For rotation/group/structured placement controls, use the replacement-then-assign sequence in the reset recipe: an update_media_buy package creative_assignments replacement clears assignment trackers on every row it supplies, and omitting the entire replacement array leaves assignments unchanged. Empty arrays and null are not accepted on writes.
Supporting sellers MUST return trackers in list_creatives assignments.assigned_packages[] and get_media_buys packages[].creative_approvals[]. Return the complete assignment-scoped list, preserving events, URL templates, order, and duplicate occurrences, or [] when there are no assignment trackers. This list excludes the creative’s own trackers, which remain in its assets and also fire. Buyers can copy a nonempty list back as authored assignment state without duplicating the creative’s trackers; use the reset recipe for an empty readback list. After an assignment merge, the buyer creative’s package assignment trackers apply alongside that creative’s trackers; the seller MUST validate the resulting combination or reject the atomic merge.
This request assigns one existing creative to two packages with different measurement values. It requires the unreleased 3.3 assignment fields; each tracker follows the assignment tracker schema. The request is validated against the source schema by the assignment-tracker tests.
Replacing a creative on a package
Areplace operation swaps the creative on one package in a single atomic step: replaces_creative_id stops serving there and creative_id takes its place. The seller traffics the replacement as a new serving object, so it is reviewed for that package like any new assignment. Send it only to a seller that lists replace in creative.assignment_operations.
The replacement takes over the replaced assignment’s authored settings, so a swap changes the creative and nothing else:
weightand placement routing (placement_idsandplacement_refs);- rotation settings:
rotation_mode,group_id, andsequence_position; - assignment
trackersand thelanding_page_urloverride; - the experimental installment scope,
installment_refs.
weight supplied on the operation replaces the transferred weight. So does a supplied installment_refs for the transferred installment scope. A placement_ids supplied on the operation replaces the transferred placement routing entirely: neither the replaced assignment’s placement_ids nor its placement_refs transfer. To change the transferred trackers or landing page in the same request, follow the replace with an assign for the replacement creative; operations apply in order and the request is atomic.
The seller MUST validate every transferred setting against the replacement, including tracker-slot capacity and events for its format, whether the landing-page override can apply to its clicks, and any destination review, and MUST reject the atomic request with the existing assignment errors rather than drop or partially apply a setting. Readback in list_creatives and get_media_buys creative_approvals[] shows the transferred settings on the replacement’s row.
Assigning to specific installments (experimental)
In AdCP 3.3, optionalinstallment_refs on an assign or replace operation limits the assignment to some installments of the package: one post of a creator package, one episode’s host read, one issue of a print run. Without it the assignment applies to every installment, as before. Each entry is a canonical installment reference, a collection_ref and an installment_id.
Buyers MUST NOT send installment_refs unless the seller lists media_buy.installment_creative_assignment in experimental_features on get_adcp_capabilities. A seller that ignored the field would run the creative on every installment, so it waits on the capability (versioning rule 4). A seller that does not support it MUST reject it with UNSUPPORTED_FEATURE. Send it only on assignment_operations: the deprecated assignments[] row and the creative_assignments rows of the deprecated create_media_buy and update_media_buy don’t carry it.
- Which installments. Each ref MUST name an installment the package bought: one in the
installmentsof the product its purchase references. The seller rejects any other ref withVALIDATION_ERROR, witherror.fieldat that ref, such asassignment_operations[1].installment_refs[0]. A run-of-collection product names no installments, so it has none to scope to. - Rotation and routing. Within one installment, weight, rotation and placement routing work as they do today, over the assignments that apply to that installment. Placement routing and installment scope intersect: a creative with both serves only in those placements of those installments. An installment that no assignment applies to has no creative from this package, and the seller MUST NOT serve it a creative scoped to another installment.
- Change cutoff. An operation changes an installment when it adds or removes a creative there, or changes the weight or routing of one that applies there. An assignment without
installment_refsapplies to every installment, so changing it changes them all, and areplacechanges every installment either creative applies to. When an operation changes an installment whosedeadlines.change_cutoffhas passed, the seller MUST reject the request withCREATIVE_DEADLINE_EXCEEDEDand name the installment, witherror.fieldat the ref when the operation names it, otherwise at the operation. It MUST NOT accept the change silently. The request is atomic, so it doesn’t apply the change to the other installments alone either. The package’screative_deadlineapplies as before. - Changing the scope. A supplied
installment_refsreplaces the assignment’s installment scope, and omitting it on anassignupsert keeps the scope. To return an assignment to every installment, use the atomicunassign/assignreset recipe without the field. Areplacecarries the replaced assignment’s scope over unless it supplies its own.unassignandmergerejectinstallment_refs: anunassignremoves the creative from every installment it applied to, so to drop one installment,assignthe remaining ones. - Readback. Sellers that list the feature return
installment_refson every assignment that has a scope, inget_media_buyspackages[].creative_approvals[]andlist_creativesassignments.assigned_packages[]. They omit it when the assignment applies to every installment.
installment_refs; the installment creative assignment tests validate it against the source schema.
replace of an assignment without installment_refs would change the earlier installments too, and the seller would refuse it.
Creative object
New 3.2 integrations use
format_kind with format_option_ref when routing depends on a product’s declared option. A compatibility implementation may accept the legacy branch from an older peer, but never mixes both shapes.
When uploading for a known target product, buyers MUST verify each creative manifest against that product’s canonical format_options[]. The manifest MUST include every asset slot that the selected format option declares as required, keyed by that slot’s asset_group_id. A library creative may be stored before selecting inventory; product-specific validation applies when the target becomes known, before assignment. Library storage alone does not establish product acceptance.
Format conformance
This is the seller’s side of the same contract: what a format option declares is what the seller accepts. A creative targets the option itsformat_option_ref names. Without a reference, it targets the option of each package it is assigned to. Where publisher or placement declarations narrow that option further, the effective declaration is their intersection (see effective acceptance).
The conformance codes are CREATIVE_SIZE_MISMATCH, CREATIVE_VALUE_NOT_ALLOWED, CREATIVE_VALIDATION_FAILED_GENERIC, and VALIDATION_ERROR or INVALID_REQUEST raised against the creative’s assets.
- Declared parameters bind the seller. A seller MUST NOT refuse, with a conformance code, a creative that satisfies a parameter the targeted option declares on the grounds of that parameter, and MUST NOT enforce a narrower value than the one declared. A declared parameter is the whole constraint for its slot. When an option declares
main_image_sizes: [{ "width": 600, "height": 400 }], a 600×400main_imageconforms, and a seller that also wants other sizes declares them. - An absent closed set does not narrow. A slot is limited to a closed set of values only when the option declares one, such as
cta_valuesorallowed_values. With nocta_values, thectaslot takes free text within any declaredcta_max_chars, and the seller MUST NOT refuse a CTA asCREATIVE_VALUE_NOT_ALLOWED. That code applies only to a value outside a declared list. - Other absent narrowing parameters set no limit. An option that omits a narrowing parameter (
title_max_chars,body_text_max_chars, a size list, a duration range) imposes no limit through it. An optional slot such asiconmay be left out. Whether the seller may still hold a limit it has not declared is whattechnical_requirements_completeanswers. When the effective declaration assertstrue, the seller has no undeclared technical limit, so it MUST NOT refuse, with a conformance code, a creative that conforms to every parameter of the option. Without that assertion the omitted constraint is undeclared, as technical completeness describes, and a seller that enforces a limit SHOULD declare it on the option. - Refusals outside format conformance are unaffected. Content-policy, brand-safety, and accessibility review failures use
CREATIVE_REJECTED, orstatus: "rejected"when review completes after the sync. A seller’s advertising policy usesPOLICY_VIOLATION. A missing destination URL usesCREATIVE_MISSING_CLICK_URLwhen the option requires one. A corrupt or unfetchable asset, or asset metadata that the inspected bytes contradict, is a failure of the asset rather than of the option’s parameters. None of these grounds narrows a declared parameter.
error.details: allowed_values with CREATIVE_VALUE_NOT_ALLOWED, or the accepted sizes with CREATIVE_SIZE_MISMATCH. The buyer can then tell a mismatch with the declaration from a seller-side rule.
Creative revisions
Buyers may sendrevision_id to any 3.2 peer. When the agent advertises
creative.supports_revisions: true, buyers may rely on it to correlate one
immutable input state through sync, review, readback, and delivery. Without the
capability, the receiver may ignore the field and the buyer cannot rely on
revision guarantees. A supporting seller echoes it on accepted created, updated,
and unchanged items and omits it on failed and deleted items.
The identity is (creative_id, revision_id). Reusing that pair with identical
canonical revision content is safe even under a new idempotency_key. Reusing
it with changed content fails that creative item with
CREATIVE_REVISION_CONTENT_MISMATCH and leaves its prior state unchanged; other batch items may still process. Mint a new revision_id for intentional
content changes. Metadata-only changes to name or tags, and assignment
changes, do not require a new revision. The seller checks idempotency_key
conflicts first, then revision content.
Canonical revision content is RFC 8785 JCS of the effective buyer-authored
creative state after applying existing sync mutation semantics, then removing
exactly the top-level creative_id, revision_id, name, tags,
status, weight, placement_refs, and placement_ids fields. Sellers do not
materialize defaults or normalize values before this comparison. Nested fields
with those names remain content. Duplicate JSON member names are rejected.
An allowed omitted localization preserves the prior topology before
comparison. localization: null removes localization from the effective state
before comparison, so a later allowed omission represents that same
unlocalized state. URL identity is the submitted URL string (plus
any submitted digest), so use immutable or digest-bound asset references when
byte-level identity matters.
A different revision ID with content identical to the current canonical state
is accepted as updated, becomes current, and preserves the existing review
state. A seller atomically rebinds any in-flight review to that new
identical-content ID. A previously bound historical ID must still match its
retained fingerprint and, when its content differs from current, enters review
again if accepted. A different revision with changed content enters review. Sellers retain revision
fingerprint bindings for the creative’s lifetime (and any soft-purge tombstone
window); a hard purge starts a new creative incarnation. Revision IDs are not
ordering counters—buyers serialize writes, and stale review results for older
revisions cannot change the current revision or status.
When an existing unversioned creative first adopts revision identity, identical
effective content is accepted as updated, binds the supplied ID, and preserves
review state. If content also changes, the seller binds the ID only when the
ordinary update is accepted, and changed content enters review.
An omitted revision_id preserves current revision identity only for
content-equivalent updates. If a supporting seller accepts changed content from
a legacy unversioned caller, it clears current revision identity and does not
mint one; later readback, webhooks, and delivery omit the field while historical
bindings remain retained. Prior approval does not transfer, and an accepted
content-bearing unversioned update enters the ordinary review lifecycle.
With dry_run: true, the seller evaluates existing revision conflicts and may
echo the simulated revision, but it does not reserve an ID, change bindings or
tombstones, select a current revision, or alter review state.
When an item carries representation_selection, its creative_id and
revision_id must equal the selection lineage. The seller binds revision
identity to representation_selection.revision_content_digest, which commits
to the complete CreativeRepresentationSet,
not to the selected manifest bytes alone. The actor that emitted the selection
must first verify the digest against the complete set. A downstream seller that
receives only the selected output can enforce stable digest reuse, but cannot
claim it independently inspected representations it never received.
The seller separately verifies selected_output_digest with the same manifest
projection used by build_creative: remove top-level $schema,
representation_selection, creative_id, revision_id, name, tags,
status, weight, placement_refs, placement_ids, inputs, and
then include every other field. It tracks
(selected_representation_id, selected_output_digest) as the execution review
fingerprint. A changed selection or changed derived output is an
updated creative and follows ordinary re-review even when the source-set
revision_id and digest remain unchanged. list_creatives returns the exact
current selection lineage while that execution remains current.
The seller never performs that replacement implicitly. Once accepted, the
selection is pinned even if later product or seller capabilities would choose
a different representation. Capability drift affects future resolution and
assignment checks; it does not mutate the library creative or start re-review.
The buyer must explicitly resolve again with build_creative and submit the
new selected output here. This sync response acknowledges the update and starts
ordinary re-review. If the seller can no longer serve the pinned execution, it
uses the ordinary seller/system status-change and media-buy impairment
surfaces without substituting another representation.
A sync item carrying representation_selection MUST omit localization,
including null, in this version, and the stored creative must not already
have localization that ordinary omission would preserve. Remove an existing
topology first with a separate accepted sync carrying localization: null and
no representation_selection, then submit the selected output. Localization
replaces materialized serving assets and cannot be treated as digest-neutral library metadata. A future
localized representation-set contract must define locale topology inside the
pre-binding revision and selected-output projections explicitly.
Revision support does not add staged activation or revision history. Unless
the seller applies the change under live creative updates,
a newly accepted content revision follows the ordinary creative update and review
lifecycle, and prior approval does not transfer to changed content. The
buyer-initiated transition is acknowledged on this response rather than a
creative.status_changed webhook; subsequent seller/system review transitions
use the ordinary webhook. The prior revision is not kept serving during review.
A revised creative under re-review is ineligible for delivery like any other
pending_review creative until it re-reaches approved. Other creatives
assigned to the same package are unaffected and continue under the seller’s
ordinary selection behavior. A package that relies only on the revised creative
therefore has a serving gap by default. A seller that declares
creative.live_updates with serving: "staged" keeps the prior version serving
instead; see live creative updates.
Creatives produced through build_creative
become buyer-authored revision state when the buyer accepts and syncs the
returned manifest, choosing the creative_id and minting (or omitting) the
revision_id. Seller-side drafts before that sync boundary are outside AdCP’s
revision history; seller transformation and transcoding after the boundary do
not mint buyer revision IDs.
Live creative updates
Experimental in 3.3. Sellers that implement it list
creative.live_updates in get_adcp_capabilities.creative_id. It does not pause packages, mint a new ID, or swap assignments. The seller declares which changes it applies in place and how the creative serves while it decides each one, and refuses the rest with one precise error.
A creative is live when its status is approved and it has at least one assignment on a package that is not canceled, whose flight has not ended, and whose media buy is not in a terminal state. A paused package still counts: on many ad servers a trafficked creative is fixed whether or not its line is paused. So does a buy that has not started, so a declaring seller may refuse before launch a change that an undeclared seller would accept. A creative that is not live, including one in processing, pending_review, suspended, or rejected, takes any change as an ordinary upsert. Liveness is evaluated against the state before the request: assignment changes in the same request do not affect it.
Change kinds. Buyer and seller classify a sync item by diffing it against the version of the creative that serves, after applying ordinary upsert semantics, so both compute the same answer:
Adding, removing, and changing an asset all count.
name and tags are not a kind: a declaring seller always accepts changes to them on a live creative, without review. status, weight, and placement fields keep their own rules.
Edit or swap. An in-place change keeps one creative_id, so delivery, measurement, and frequency keep accumulating under one identity. That fits changes to the same ad: a tracker, a click-through, a corrected asset. A change that makes it a different ad belongs on a new creative_id swapped in with an assignment_operations replace, which separates reporting and frequency and gives the old creative a defined end. Every seller that declares creative.live_updates lists replace in creative.assignment_operations, so the swap is always available where this section applies. The protocol does not draw that line by content. The seller draws it through what it lists in in_place: a seller that treats wholesale content replacement as a new ad leaves asset_content out, or declares it paused_for_review, and refuses or pauses it. Syncing a new creative_id stays available to every buyer, declaring seller or not.
Out of scope in this experiment. Dynamic creatives, whose content and landing URL vary per impression by design (for example DCO driven by variables, catalog items, or macros), have no single “after” for a seller to review, so the change-kind diff does not apply to them. The experiment does not define how a seller reviews or stages a change to one. A declaring seller MAY refuse an in-place change to a dynamic creative with CREATIVE_LIVE_UPDATE_UNSUPPORTED, naming asset_content, and the buyer syncs a new creative_id. Audience is not a creative change: it is targeting on the package. Rotation and weight belong to the assignment and placement. None is a change kind, and nothing in this section changes them.
Serving modes. For each kind it applies in place, the seller declares one mode. in_place has at most one entry per kind.
Modes rank from least to most disruptive:
uninterrupted, staged with on_rejection: "keeps_prior", staged with on_rejection: "stops", paused_for_review. When one item makes several kinds of change, the most disruptive applies, and the item is refused if any kind is refused. For uninterrupted, the seller’s decision inside the call is its review of the change: prior approval still does not transfer to changed content, the seller re-approves it synchronously. A seller whose review is asynchronous, or split across publishers, cannot declare uninterrupted for kinds it reviews.
Before sending a change. The creative.live_updates capability is a floor: each listed kind is accepted on every live creative in its listed mode or a less disruptive one. A listed kind MAY be accepted for creatives beyond the floor, for example on ad servers that allow more, and an unlisted kind MAY still be accepted for some creatives. For the exact outcome of one change, send it with dry_run: true: the seller returns the same mode or refusal it would apply, without changing anything; a dry-run staged_update carries the evaluation time as staged_at.
Staged updates. While a staged update is pending:
- The prior approved version is the only version that serves, on every assignment.
list_creativesreturns itsassets,revision_id, andstatus, plusstaged_updatewith the update’s ownstatus(processing,pending_review, orrejected), itsrevision_idwhen the sync supplied one, itschange_kinds, andstaged_at. Package rows inget_media_buyscreative_approvals[]keep describing the version that serves. - The sync response’s top-level
revision_idechoes the request, so it names the staged revision, while the item’sstatusdescribes the serving version. - A creative has at most one staged update. Syncing another staged change supersedes the pending one, which never serves. Syncing the content of a pending staged update again leaves it and its review unchanged; under a new
revision_id, the seller rebindsstaged_update.revision_idas it would rebind identical current content. Syncing the content of a rejected staged update resubmits it for review. Syncing content identical to the serving version withdraws the staged update, and the item returnsaction: "updated"withoutstaged_update; so does a sync the seller applies in another mode, since its content no longer carries the staged change. Neither supersession nor withdrawal fires a webhook. - Review is one decision across every assignment. If review rejects the update for any package, the outcome is a rejection; the seller never promotes it on some assignments only.
- Approval promotes the update on every assignment: its content and
revision_idbecome the creative’s current state,staged_updateis removed, and the seller firescreative.staged_update_changed(see the notifications paragraph below) withoutcome: "promoted". The creative’s status does not change, socreative.status_changeddoes not fire. - Rejection depends on the declared
on_rejection. Withkeeps_prior(the default), the prior version keeps serving,staged_update.statusbecomesrejectedwith arejection_reason, and the seller firescreative.staged_update_changedwithoutcome: "rejected"andcreative_status: "approved". Withstops, the creative goes torejectedwith the prior version’sassetsandrevision_id,staged_updateis removed, and the seller surfaces impairments on its buys as for any revocation. That is an ordinaryapproved → rejectedtransition (reason_code: "policy_revocation") oncreative.status_changed, and the seller also firescreative.staged_update_changedwithoutcome: "rejected"andcreative_status: "rejected". - Any other transition discards it. When the seller moves the creative out of
approved(re-review, suspension, revocation, or archival) or the creative stops being live, the seller discards the staged update without a fire. - When the seller supports revisions, delivery rows carry the
revision_idthat actually served, so reporting splits at promotion while thecreative_idjoin is unchanged.
creative.status_changed: an approved → approved fire would fail the closed validator of a buyer on a release that predates live updates. The seller reports it on the separate experimental creative.staged_update_changed event (creative-staged-update-changed-webhook.json), and only to notification_configs[] entries whose event_types[] include it. A buyer that does not register it never receives it and reads the outcome from staged_update on list_creatives. See lifecycle webhooks.
In every mode, one creative_id is one creative. An accepted or promoted change applies to every assignment of the creative on every media buy, and the seller MUST NOT leave a prior version serving alongside the new one beyond the declared max_propagation_seconds (cache, SSAI, and exchange propagation). An assignment’s own landing_page_url or trackers still apply on that assignment: a library clickthrough change does not reach an assignment that overrides it.
Refusal. A declaring seller fails an item it does not apply in place to a live creative with CREATIVE_LIVE_UPDATE_UNSUPPORTED, and leaves the creative, its review state, and its serving unchanged. Other items in the request still process. error.details SHOULD conform to error-details/creative-live-update-unsupported.json: refused_changes and live_package_ids. To make the change anyway, sync it as a new creative_id and swap it in with an assignment_operations replace on each live package. A declaring seller MUST list replace in creative.assignment_operations, so this swap is always available. A seller that does not declare creative.live_updates is not covered by this section: the original rule applies unchanged (creatives on active, non-paused packages cannot be updated, and the refusal is INVALID_STATE), so buyers handle both codes.
Native localization
Discover support before writing. The agent’sget_adcp_capabilities.creative.localization block advertises structural
support, RFC 4647 Lookup, and an optional target ceiling. Locale, format, and
account support is validated against each request. A seller MUST reject an
unsupported locale/format pair, duplicate target locale/ID, target locale/ID
that reuses the source value, missing materialized assets, or invalid default
reference before mutating seller systems or the creative library. JSON Schema uniqueItems
compares whole objects and is not sufficient for those property-level rules;
conformance verifiers consume the schema’s x-adcp-validation constraints.
This is the only localization mutation surface. Inline package creatives in
create_media_buy and update_media_buy reject localization; sync the
localized library creative here, then assign it by creative_id.
target_variants may be empty to declare the canonical locale of a monolingual
source-only creative, such as a single fr-CA creative for French-only Québec
inventory. Do not invent a second locale variant merely to declare source
language.
default_locale_variant_id may select source or target. This task never asks
the seller to translate: use buyer tooling, build_creative, or a separate
translation/transformation agent first, then sync the resulting assets.
At delivery, the seller applies RFC 4647 Lookup to ordered locale preferences.
Each progressively truncated requested range matches only an equal available
canonical tag; it does not prefix-match sibling regional tags.
The ordered list comes from the seller’s serving environment and is outside
this task: AdCP does not define how browser, content, geography, user, app, or
platform signals produce it or their precedence.
For each preference, a strict miss is followed by the most-specific matching
locale_fallbacks rule before the next preference is tried. The example’s es
rule lets an es-ES preference use loc_es_mx; without that rule, no regional
substitution is inferred. After every preference misses both paths, the seller
follows unmatched_locale_action: serve default_locale_variant_id or make the
creative ineligible. It never silently assumes the source is the default.
Standalone library sync has no product context and does not apply product locale
policy. When assignments[] binds a creative to a package whose effective
format option has locale_policy, the
seller uses RFC 4647 Basic Filtering to derive the eligible source/target
variant set before running the buyer algorithm above. For example, seller range
fr accepts fr-CA and fr-FR. The assignment fails with
CREATIVE_LOCALE_NOT_ACCEPTED if no materialized variant matches. If
unmatched_locale_action is serve_default, the default variant must also be
seller-eligible. Buyer fallback and default rules never override the product or
placement constraint; nonmatching variants remain stored for other products.
The seller runs this check independently for every placement where the
assignment may serve. If one placement fails, the assignment is rejected unless
the buyer narrows its placement scope to compatible placements.
Accepted localized results include localization as a complete
source-plus-target variant list. The response preserves the request’s exact
source ID/locale, target ID/locale set, fallback-rule set, default ID, and unmatched action. Each
variant returns complete resolved assets under the same buyer-assigned
locale_variant_id; no seller- or platform-assigned variant ID is required.
The enclosing creative’s single status governs the complete set. If the
seller cannot read back any one of those values exactly, the item fails rather
than silently falling back to the source language.
Every accepted localized result (created, updated, or unchanged) MUST
carry top-level aggregate status and complete localization; failed and
deleted results MUST omit localization. A later
list_creatives read preserves the exact source/target identities.
delete_missing remains creative-scoped. If it archives a creative, every
locale variant follows the whole creative lifecycle, and omitted target locales
are never treated as missing creatives. A non-null localization object
transactionally replaces top-level source assets and the complete locale set;
failure leaves the prior state unchanged and must not expose orphaned locale
variants.
Null removes localization. Omission preserves localization only when top-level
source assets exactly equal the prior source assets. The normal active-delivery
update protection applies to all three operations.
Promoting a build_creative variant
When a buyer keeps a produced build leaf, the canonical promotion is to use the keptbuild_variant_id as the new creative_id. The seller does not need to hold a separate lineage mapping; delivery reporting can join back to the build leaf through the normal creative_id.
test=false
get_creative_delivery uses creative_id as the join key. A workflow that mints a different library id instead of using the kept build_variant_id loses this protocol-visible join unless a future scoped lineage field is adopted.
Asset structure
Assets are keyed by role name. Each role contains the asset details:test=false
published_post and the payload contains a post URL or platform post ID instead of uploaded media bytes. Buyers can submit these assets through the canonical creative path, for example format_kind: "video_hosted" plus the product’s format_option_ref, instead of creating a platform-specific format_id. If the seller can resolve the post but lacks a required downstream platform connection, such as the publisher identity that owns the post, the correctable error is AUTHORIZATION_REQUIRED. New implementations should include error.details.missing_connections[] so the caller can send a human through the correct connections flow and retry after authorization is restored.
Assignments structure
Assignments are at the request level, mapping creative IDs to package IDs. Standalone creative agents that do not manage media buys ignore this field. Revisions. Each applied assignment change (assignments and assign, unassign or replace in assignment_operations) advances the revision of every media buy whose package assignments it changed, once per buy per committed request, in the same atomic write as that buy’s assignment change, and appends a history entry to that buy. This is new in 3.3; 3.2 sellers did not advance it. sync_creatives accepts no media-buy revision precondition, so a buyer that holds a media-buy revision read before the sync and then sends update_media_buy or control_media_buy receives CONFLICT and re-reads. A dry run, a rejected assignment, a no-op assignment and an exact idempotency replay advance nothing. Each created or changed creative also advances its own seller_revision when the seller maintains one.
test=false
@adcp/sdk server-side): the typed syncCreatives(creatives, ctx) signature does not surface assignments as a positional argument. The wire envelope lands on RequestContext.input, so handlers read ctx.input.assignments to fan out package bindings and emit creatives[i].assigned_to in the response. The same escape hatch applies to any request field the typed signature intentionally does not model. See adcp#5797 for the trace that motivated this note (SDK ≥ 11.1.0 threads params into ctx.input; earlier lines dropped the field at the projector seam).
Response
Responses use discriminated unions — a response has exactly one of three shapes, never mixed: 1. Synchronous success — per-creative results:creatives- Results for each creative processed (includes both successful and failed items)dry_run- Boolean indicating if this was a dry run (optional)
errors- Array of operation-level errors (auth failure, service unavailable)
status- Always"submitted"task_id- Handle for polling viaget_task_statuson the A2A profile (or the advertised AdCP polling task on MCP), or receiving a webhook on completionmessage- Optional human-readable explanation of the queue state
creatives array lands on the task completion artifact, not on the submitted envelope. Per-item async review (one creative in pending_review while the rest of the sync resolves synchronously) belongs on the synchronous success branch with status: "pending_review" on that item, not here.
Each creative in the success response includes:
- All request fields
platform_id- The seller’s identifier for the creative in its source of truth (whenactionis notfailed).list_creativesreturns the same value.revision_id- Exact request revision on acceptedcreated,updated, orunchangeditems when supplied. Omitted onfailedanddeleted.action- Lifecycle operation performed by this sync:created,updated,unchanged,failed,deletedstatus- Advisory review-lifecycle state (CreativeStatus):processing,pending_review,approved,suspended,rejected,archived. A UI hint and polling-scheduling signal — not a spend-authorization gate. Orthogonal toaction—actiondescribes what the sync did,statusdescribes where the creative is in the review lifecycle. Values come fromCreativeStatusonly, never fromCreativeAction(never putcreated/updated/failedinstatus). Sellers with async review returnprocessingorpending_review; sellers with synchronous review MAY return a terminal value (approved/rejected) orsuspendedwhen a recoverable dependency/authorization gate prevents serving. Buyers MUST NOT gate downstream spend or package activation onstatus: approvedfrom this response — reconcile vialist_creativesor a signed review webhook before committing spend. Authoritative state is always vialist_creatives. MUST be omitted whenactionisfailedordeleted— failed items have no meaningful review state (seeerrors); deleted items are gone from the library. The schema enforces the omission rule via a conditional constraint.localization- Exact materialized source/target locale state. Required with top-levelstatuson every accepted localized item, omitted on failed/deleted/unlocalized items. The top-level status is the single creative-wide review state.errors- Array of error messages (only whenaction: "failed")warnings- Array of non-fatal warnings (optional)
Common scenarios
Bulk upload
Upload multiple creatives in one call:Generative creatives
Use the creative agent to generate creatives from brand identity data. See the Generative Creatives guide for complete workflow details.Dry run validation
Validate creative configuration without uploading:Scoped update with creative_ids filter
Update only specific creatives from a large library without affecting others:- Scoped updates: Only specified creatives modified, even with 100+ in library
- Error recovery: Retry only failed creatives after bulk sync validation failures
- Performance: Publisher can optimize processing when scope is known upfront
- Safety: Explicit targeting reduces risk of unintended changes
Async approval workflow
Two distinct async patterns — match the right one to the agent’s behavior: Per-creative async review (common): the sync operation itself resolves synchronously, but one or more creatives require downstream review (brand safety, policy compliance). Items in review come back on the synchronous success response withstatus: "pending_review" (or processing during ingestion). The buyer reconciles terminal state via list_creatives or a webhook.
Operation-level async (less common): the whole sync is queued — the seller cannot return any per-item results before responding, because ingestion is batched or governance review gates the entire sync. The response is a submitted envelope:
- Top-level
status: "submitted"withtask_id message— optional human-readable explanation- No
creativesarray on this envelope
get_task_status on the A2A profile (or the advertised AdCP polling task on MCP), or wait for the webhook. The completion artifact carries the creatives array with per-item action/status results; operation-level failures surface as status: "failed" on the task.
See: Webhooks for webhook configuration.
Sync modes
Upsert (default)
- Creates new creatives or updates existing by
creative_id assignments[]remains the deprecated additive assignment shorthandassignment_operations[]can traffic existing IDs without resending creative bodies, using the operations the seller lists increative.assignment_operations:assignupserts weight/placement scope,unassignremoves one assignment,replaceatomically swaps an existing creative for a replacement that the seller traffics as a new serving object and that keeps the replaced assignment’s settings (see Replacing a creative on a package), andmergedeclares that a seller-assigned creative already on the package is the buyer’s creative, so the seller keeps the existing serving object, approval, and delivery continuity and reports it under the buyer’screative_id(see Merging a seller-created copy)- Updates provided fields, leaves others unchanged
- Use
creative_idsfilter to limit scope to specific creatives
Seller-assigned creative IDs
list_creatives also returns creatives that entered the seller’s library outside sync_creatives, under a creative_id the seller assigned.
- Managing one. A buyer updates such a creative by syncing it under its
creative_idas-is. That is the normal upsert, subject to the same active-delivery protection as any update. Ownership of the account, not the surface that created the creative, decides what the buyer can manage, as for media buys (account ownership, not creation surface). - Collisions. If a buyer syncs a creative it means as new and its
creative_idequals an existing one, the sync updates the existing creative. The buyer detects this fromaction: "updated"or"unchanged"where it expected"created". Buyers SHOULD use UUIDs or a stable prefix for their IDs. delete_missing. A seller that declarescreative.stable_creative_idsMUST NOT archive a seller-created creative underdelete_missing: true, including one a buyer has since updated, because a full sync replaces the buyer’s own set. A seller that does not declare it may archive them, as in 3.2, so buyers SHOULD NOT usedelete_missingwith such a seller when seller-created creatives matter.
Merging a seller-created copy
A seller’s operator or system can create its own copy of a creative the buyer already synced and attach it to a package.list_creatives then shows two rows for one creative: the buyer’s acme_video_001 and, on pkg_premium_video, seller-assigned slr_88412. A replace operation would swap them, but the seller traffics the replacement as a new serving object, so it is reviewed again and delivery restarts. A merge operation says “slr_88412 on this package is my acme_video_001”: the seller keeps the existing serving object, approval, and delivery, and reports them under the buyer’s creative_id.
merge unless the seller lists it in creative.assignment_operations; a seller that does not list it rejects merge with UNSUPPORTED_FEATURE. When the older creative.supports_assignment_merge flag is true, the list includes merge; where they disagree, the list governs. creative_id need not already be assigned to the package. If it is, the seller retires that assignment’s own per-package object. The merged assignment keeps the weight and placement routing of merged_creative_id’s assignment; a later assign operation in the same request can change them, because operations apply in order.
Verification. The seller verifies every merge in the request. Assignment operations are atomic, so if any merge fails, the seller applies no operation and returns one CREATIVE_MERGE_REJECTED error. error.field points at the first rejected operation, and error.details SHOULD conform to error-details/creative-merge-rejected.json, listing every rejected merge with its operation_index and a reason:
The buyer can drop or fix the rejected merges and resubmit the rest in one request.
If the seller needs a person to confirm a match, it returns the
submitted envelope, and the task’s completion artifact carries either the success response with merges[] or CREATIVE_MERGE_REJECTED. Because the operations in a request are atomic, the rest of the batch waits on that confirmation, so buyers SHOULD send a merge that may need confirmation in its own request. With dry_run: true, the seller runs the same verification, applies nothing, and reports the merges it would apply.
Response. A successful response carries merges[], one entry per applied merge in request order: creative_id, package_id, merged_creative_id, and the inherited approval_status. The buyer learns each merge’s outcome from the response itself, without a follow-up read. A merge-only request returns an empty creatives array.
- The buyer’s assignment inherits
merged_creative_id’s approval on the package. Sellers MUST NOT review it again unlesscreative_id’s content differs frommerged_creative_id’s. merged_creative_idno longer has an assignment on the package. It is not purged. It stays inlist_creativeswhile it still exists in the seller’s source of truth, and otherwise moves toarchivedlike any creative the seller’s source of truth no longer holds.- Delivery for that object is reported under
creative_idfrom the time of the merge. Delivery before the merge stays undermerged_creative_id; sellers MUST NOT restate it. - A seller that emits
creative.assignment_changedsendsunassignedformerged_creative_idandassignedforcreative_id(orapproval_changedif it was already assigned), with the sameobserved_at. A seller with the experimental account change feed records twocreative_assignmentchanges sharing onebatch_id,unlinkedandlinked, withorigin.kind: "adcp".
merged_creative_id MUST be a creative that entered the library outside sync_creatives. Merging a duplicate that a buyer synced is out of scope, because one principal must not take over another principal’s creatives.
Dry run
- Rehearses the same
sync_creativesacceptance path without committing library, assignment, review, or serving changes - Returns operation-level errors, per-creative failures, assignment errors, and warnings the seller can determine before mutation
- Does not create or update creatives, package assignments, review state, or serving state
- Use for seller trafficking acceptance checks; use
validate_inputfor manifest-only canonical/product preflight
Error handling
Sellers that declare
creative_specs.vast_validation of document or wrapper additionally validate vast assets at sync time (including dry_run) and can return VAST_PARSE_FAILED, VAST_VERSION_MISMATCH, or VAST_WRAPPER_DEPTH_EXCEEDED. See VAST Validation.
Best practices
-
Use upsert semantics - Same
creative_idupdates existing creative rather than creating duplicates. This allows iterative creative development. Note: updates are blocked for creatives in active delivery (see #6), except as #6 describes for a seller that declarescreative.live_updates. -
Rehearse seller acceptance first - Use
dry_run: truewhen you need to catch upload, upsert, assignment, account, policy, or format errors before mutating the seller’s creative library. Usevalidate_inputearlier in the workflow only for manifest-structure preflight or multi-target product comparison. -
Batch assignment operations - Use one idempotent
assignment_operations[]call for assignment updates, removals, and replacements, using only the operations the seller lists increative.assignment_operations. This keeps creative trafficking separate from MediaBuy commercial controls and avoids races between calls. - CDN-hosted assets - Use publicly accessible CDN URLs for faster processing. Platforms can fetch assets directly without proxy delays.
- Brand identity - For generative creatives, validate brand identity schema before syncing to avoid processing failures.
-
Active delivery protection - Creatives assigned to active, non-paused packages cannot be updated or deleted via
delete_missing. Pause the package first, useassignment_operationsto unassign or replace the creative where the seller lists those operations, or create a new creative with a differentcreative_id. The one exception is a seller that declares the experimentalcreative.live_updatescapability: it applies the changes it lists to a live creative under the samecreative_id, whether or not the package is paused, and refuses the rest withCREATIVE_LIVE_UPDATE_UNSUPPORTED(see Live creative updates). Every other seller keeps the rule above and refuses withINVALID_STATE.
Related tasks
- Canonical formats - Check product and publisher format contracts before upload
list_creatives- Browse and filter creatives in a librarybuild_creative- Build manifests from library creatives or generate from scratchpreview_creative- Generate previews of creative manifests- Creative Asset Types - Technical requirements for assets