Advertiser

Overview

An Advertiser in Apostra is the commercial media identity on whose behalf campaigns run: a brand care of an operator. The brand answers whose products are being advertised; the operator answers which organization drives the buying. This is an Apostra product projection, not an assertion that AdCP collapses the two entities: AdCP keeps Brand, Operator, Account, and Agent separate. For buyer-declared AdCP accounts, the natural key combines the BrandKey (including its country qualifiers), operator domain, optional operator-unit ID, fixed currency, and sandbox mode. An upstream-managed account_id instead names an entry in the seller’s own namespace, whose declared account_scope may be operator-, brand-, operator-and-brand-, or agent-wide. See AdCP Accounts and agents. Direct buying is the identity case where the brand operates its own seat. For example, Coca-Cola buying directly from an account registered to coca-cola.com is “Coca-Cola care of Coca-Cola”; Coca-Cola through WPP is “Coca-Cola care of WPP.” Self-serve is an interface, not an operator identity: using Apostra directly does not replace Coca-Cola with “self-serve” as the operator. Likewise, an agent is the software acting for the operator, not the operator itself. When a buyer account has no registered domain, current v2 outbound AdCP calls use interchange.io as a platform operator fallback until the account records its real domain; that fallback is an implementation compromise, not the meaning of self-serve. In the current Apostra v2 buyer API, an advertiser is also the top-level resource container for media. Every campaign, creative, audience, frequency cap, and linked partner account belongs to one. The authenticated buyer account establishes the operator context, so the v2 advertiser payload does not repeat an operator field.

Media Company-managed advertisers

When a Media Company adds an advertiser for a campaign it will operate on its own inventory, the Media Company remains the operator and the advertiser is the brand it represents. Apostra binds that advertiser to the organization’s exact Storefront; the operator does not create a seller connection or switch into a separate Buyer account. The operator can select known authorized Products directly or ask for a proposal when it wants merchandising recommendations. For an exact own-supply campaign, uploading Creative records the operator’s Storefront creative decision, and confirming launch records its Storefront media-buy decision. Those decisions do not bypass ad-server creative moderation, validation, readiness, financial, or safety checks. External and sponsored buyers continue to follow the Storefront’s configured approval settings.

Renamed from Brand Agent: In v1 this concept was called a “Brand Agent”. In v2 it has been renamed to Advertiser to align with industry terminology used by Google Ads, The Trade Desk, DV360, and Amazon DSP.

Why advertisers matter

Resource ownership — campaigns, creatives, audiences, and frequency caps all roll up to a single advertiser
Commercial identity — every advertiser combines a brand reference with the operator acting for it
Brand identity — every advertiser links to a brand resolved from the AdCP brand registry (or a /.well-known/brand.json document on the brand’s domain), and keeps its own saved copy of the result
Default policies — optimizationApplyMode, UTM parameters, and frequency caps set on the advertiser flow down to its campaigns
Sandbox isolation — sandbox advertisers route every ADCP call to test accounts, so you can rehearse end-to-end flows without real spend
Linked accounts — connect the advertiser to existing accounts on upstream platforms (e.g. Snap, programmatic DSPs) for cross-platform reporting and execution
Channel preferences — record the AdCP media channels the advertiser expects to use; overlap affects automatic seller qualification without creating advertiser-owned selection edges
Reporting time-zone preference — record the buyer’s desired reporting boundary while allowing sellers to use a fixed or assigned effective time zone

Key fields

labels is the Buyer Account’s optional dimension-keyed classification for the advertiser. It is managed through the V3 MCP save_advertiser tool and read through V3 get and search; see Dimensions and labels. The advertiser resource has two response shapes:

Summary — returned by GET /api/v2/buyer/advertisers (list). A small, fixed set of row-level fields.
Full — returned by GET /api/v2/buyer/advertisers/:id (get). The complete resource with nested brand, linked accounts, UTM config, and frequency caps.

Organization roster projection

GET /api/v2/organization/advertisers returns one bounded advertiser roster over the compatibility accounts the authenticated organization context may read. It does not copy advertisers or campaigns: every entry points back to the existing advertiserId and compatibility-account boundary. Owned entries use relationshipClass: "owned". A plain advertiser row is operatingMode: "managed"; an advertiser backed by the existing confined seller-buyer sponsorship is operatingMode: "self_serve" and operatorRelationship: "client". An accepted, unexpired organization advertiser grant emits only its named advertiser IDs as relationshipClass: "delegated". The owner keeps the advertiser, Campaign IDs, and backing account. The grantee receives the grant reference, owner organization, reviewed capabilities, and expiry, but never the owner’s account ID, members, billing, unrelated advertisers, future advertisers, or private configuration. See Manage organization advertiser grants. This limited-beta projection also requires an active beta entitlement and server-side beta exposure enabled by Apostra. Each delegated roster read rechecks an accepted, unexpired grant for the exact advertiser and advertiser.read capability. Counterparty AdCP relationship reconciliation is dark prerequisite infrastructure: no customer or internal account is enrolled, and the public API does not make counterparty entries or repair available from this slice. Later activation work must separately enable both the fail-closed customer flag and runtime entitlement before any counterparty row can appear. Each resolved row includes binding provenance and resolution state, caller-relative management capability, and readiness. Pending, suspended, and disabled advertiser rows remain visible with non-ready state instead of being silently treated as active. Resolved rows deduplicate only by canonical advertiser ID; matching names or brand domains never merge advertisers or widen access. When later activation authorizes counterparty entries, exact duplicate tuples including the explicit operating mode deduplicate deterministically in the resolved entries collection, while relationships that differ only by operating mode remain distinct. Incomplete, stale, revoked, or conflicting relationships remain separately visible in the additive unresolved counterparty collection until a direct-human Seller-admin performs the explicit entitlement-gated repair. The endpoint uses authenticated account membership and active explicit grants. It never expands access from a name, email domain, CRM association, signup history, provider, external Business Manager, or Partner status. Advertiser-scoped credentials cannot read the organization roster.

Seller-managed advertiser viewer access

When Apostra enrolls a seller-managed advertiser user, the user’s current seller, advertiser, role, and capability grant are checked again on every request. A user with the read capability can list Campaign summaries through GET /api/v2/buyer/campaigns only for that exact advertiser. The advertiserId query parameter is optional, but when supplied it must match the advertiser already selected at sign-in; it cannot switch advertisers or widen access. This access does not create a buyer account or customer membership. It does not grant Campaign detail, Campaign changes or execution, reporting, other advertiser routes, organization or member settings, or billing and payment access. Missing, stale, suspended, or revoked grants are denied before Campaign data is read. Users who need another advertiser must sign in with a separate explicit grant for that advertiser.

Confirming markets and channels with your agent

When you use a V3 agent to create an advertiser or classify an empty market or channel setting, it may suggest the countries where the brand operates and the channels it is likely to buy. Review the suggestion and confirm it, change it, or choose All countries or All channels before anything is saved. We keep the suggestion with your final answer so we can improve future suggestions; the suggestion never changes what you chose.

Summary shape (list rows)

Field	Type	Notes
`id`	string	Stable advertiser identifier
`name`	string	Human-readable name (max 255 chars)
`status`	`ACTIVE` \| `ARCHIVED`	Soft-delete state
`sandbox`	boolean	When true, all ADCP calls route to sandbox accounts. Immutable after creation.
`brand`	string	Brand domain (e.g. `northwind.example`) or brand website URL
`brandCountries`	array	ISO 3166-1 alpha-2 qualifiers for this advertiser’s BrandKey market scope. Empty means all countries
`brandCountriesKnown`	boolean	`false` only for a legacy advertiser whose empty country list is still unknown; otherwise an empty list is global
`primaryCurrency`	string	ISO 4217 currency used by campaigns under this advertiser
`preferredTimezone`	string \| null	Preferred IANA reporting time zone
`currencyLocked`	boolean	Whether currency can still change through the raw v2 API
`reportingTimezoneLocked`	boolean	Whether the reporting time-zone preference can still change
`channels`	array	Editable AdCP media-channel planning preferences; overlap affects automatic matching without owning seller selection
`linkedAccountCount`	integer	Number of partner accounts linked to this advertiser. Use `get_advertiser` for the full list.
`createdAt` / `updatedAt`	datetime	ISO 8601 timestamps

Full shape (single advertiser)

The single-advertiser endpoint returns every field above plus:

Field	Type	Notes
`description`	string	Optional description (max 1000 chars)
`linkedBrand`	object	Resolved brand identity — name, domain, logos, colors, fonts, manifest
`optimizationApplyMode`	`AUTO` \| `MANUAL`	Default for the advertiser’s campaigns. `MANUAL` requires approval before applying optimizations.
`linkedAccounts`	array	Partner accounts linked to this advertiser (e.g. Snap account, agency seats)
`utmConfig`	array	Click-URL parameters appended to landing-page URLs at delivery. The v2 name for V3 `tracking.macroAdditions`; a new advertiser has none
`frequencyCaps`	array	Buyer-side caps enforced by Apostra across all publishers
`brandWarning`	string	Warning about brand resolution (e.g. manifest not found)

Brand resolution

An advertiser records a brand domain or website URL. When the brand is linked, Apostra resolves the brand identity once, from one of three sources, and saves the result as a copy that belongs to that advertiser:

The advertiser’s /.well-known/brand.json (per the AdCP spec)
The AdCP brand registry
Brandfetch enrichment

The saved copy is not shared across advertisers, and it is not kept in step with the brand’s published file. Apostra re-resolves it only when the copy is missing or can’t be read, or when you link a different brand domain (or set saveBrand: true), which is only allowed before the advertiser’s first campaign or seller-account binding. A change the brand publishes later does not reach advertisers that already linked it. Pass brand: "northwind.example" and Apostra resolves the brand identity and saves it, surfacing logos, colors, fonts, tone, and product catalog under linkedBrand when available. If the advertiser is created or updated from enrichment rather than an official registry entry, the response includes brandWarning; do not retry create for that case. After reviewing the enriched details, set saveBrand: true on an update if you want to persist the brand in the registry. If no enrichment data is available, retry create with saveBrand: true only after confirming the advertiser name and brand domain. In the brand profile preview, the V3 get({ kind: "advertiser", include: ["brandProfile"] }) read returns a summary of the saved copy as generation uses it: the brand kit, voice rules, disclaimers, and where each value came from. It is read-only, and only accounts with Creative Engines access have it. See Brand profile (preview).

See the Brand object guide for the brand resolution model in detail.

Uniqueness

The AdCP-aligned advertiser identity is BrandKey (domain, optional brand ID, and sorted country qualifiers) × operator domain × optional operator-unit ID × fixed currency × sandbox mode. The same brand domain can therefore back more than one advertiser resource when its brand ID, countries, or currency differ. Those rows are separate campaign and billing containers, not different operator identities. An AdCP 3.2 seller receives the whole BrandKey in brand: domain, optional brand_id, and countries as sorted ISO 3166-1 alpha-2 codes, because AdCP 3.2 includes the countries in the account key. A seller on AdCP 3.1 or earlier never receives countries, because its BrandRef has no such field; for that seller the country scope stays inside Apostra. A global scope sends no countries, since AdCP defines an omitted list as the global or default identity. An advertiser carries a brand ID only when the brand publishes it: the brand’s /.well-known/brand.json, or a registry entry the brand owner verified, must list that ID. A brand ID that appears only in community or enriched brand data is not stored, and the advertiser uses the domain alone. Apostra rechecks each stored brand ID against the brand’s registry entry about once a week. If the brand later stops listing an ID that sellers already know, Apostra keeps sending it so the advertiser’s existing seller accounts stay intact, and flags the mismatch to Scope3 operations. An explicitly empty country list is a confirmed global BrandKey scope. The country dimension does not block automatic matching in any declared seller country; channel overlap and the seller’s marketplace, transaction, and authority rules still apply. It does not mean the advertiser has zero markets. This differs from a legacy advertiser with brandCountriesKnown: false, whose empty response list means the scope is still unknown and must be classified before seller activation. The buyer operator domain and unit are confirmed in Buyer Setup and remain editable until the first advertiser is created. Advertiser creation is the first-use boundary and freezes that account-level operator identity. Later changes require identity migration rather than an inline edit on the advertiser. Within a buyer account and sandbox mode, creating a second resource with the same brand domain, optional brand ID, BrandKey countries, and currency returns a conflict. Sandbox and non-sandbox advertisers are tracked separately. Only one active sandbox advertiser can hold a brand identity at a time. An archived sandbox advertiser releases its brand identity, so you can create a new sandbox advertiser for the same brand, countries, and currency. An archived non-sandbox advertiser keeps its brand identity: restore it instead of creating a replacement.

Sub-resources

The advertiser is the hub for many sub-resource collections. Each lives under /api/v2/buyer/advertisers/:advertiserId/... and inherits the advertiser’s auth, brand, and sandbox context.

Collection	Endpoint root	Purpose
Campaigns	`/api/v2/buyer/campaigns?advertiserId=…`	Marketing initiatives — flight dates, budget, products, creatives (guide)
Linked accounts	`/advertisers/:id/accounts`	Existing accounts on upstream platforms (Snap, programmatic DSPs, agency seats) — see below
Catalogs	`/advertisers/:id/catalogs`	Product / offering / inventory feeds pushed via ADCP `sync_catalogs` and reused by discovery and creative generation
Audiences	`/advertisers/:id/audiences`	First-party audiences synced via ADCP for targeting and incrementality test cohorts
Property lists	`/advertisers/:id/property-lists`	Domain/email allow-and-block lists (up to 100k entries) (guide)
Event sources	`/advertisers/:id/event-sources`	Conversion event source registration (measurement guide)
Measurement config	`/advertisers/:id/measurement-config`	MMM, incrementality, and brand-lift configuration (measurement guide)
Test cohorts / plans	`/advertisers/:id/test-cohorts`, `/advertisers/:id/test-plans/:id`	Incrementality test scaffolding (measurement guide)
Hypotheses	`/advertisers/:id/hypotheses`	A/B test hypotheses
Belief state	`/advertisers/:id/belief-state`	Bayesian belief state from the measurement engine (measurement guide)
Tracking config	`/advertisers/:id/tracking-config`	Tracking macro and pixel template configuration
UTM config	inline on the advertiser	Click-URL parameters appended to landing-page URLs (set via `utmConfig` on create/update; see Click-URL parameters)
Frequency caps	inline on the advertiser	Buyer-side caps that flow down to all of the advertiser’s campaigns (guide)
Allocations	`/advertisers/:id/allocations`	Budget allocation entries used by the optimizer
Event summary	`/advertisers/:id/events/summary`	Aggregated conversion event metrics
Syndication	`/advertisers/:id/syndicate`	Syndicate first-party audiences to partner platforms
Log event	`/advertisers/:id/log-event`	Custom event ingestion (guide)

See the Buyer API Reference for the full request and response shape of each.

Tracker defaults and campaign inheritance

Third-party impression, click, and custom-event trackers are resources with stable tracker_id values. Configure advertiser defaults at /advertisers/:advertiserId/tracking-config; every campaign under that advertiser resolves those defaults when the tracking-config resource is read. Campaigns do not copy the advertiser array, so an advertiser update appears in the next resolved API response immediately. Configure campaign additions and inherited enable/disable decisions at /campaigns/:campaignId/tracking-config. The campaign stores only its local custom_tracker_urls and tracker_overrides. Its response also returns the fully resolved effective_trackers, including source_scope, inherited, effective_enabled, and status_reason, plus separate advertiser and campaign revisions. An override whose advertiser tracker was removed is retained and reported in orphaned_override_ids instead of silently targeting a different tracker. Each imported tracker retains both forms of its URL:

raw_url is the exact vendor tag supplied by the buyer.
url is the canonical form using AdCP universal macros.
mapping_artifact records the translation and documentation provenance.
source_dialect and compiler_version make the transformation reproducible.

Strict V3 writes and publishable tracker compilation limit URLs to 8,192 characters and 64 macro tokens. The V2 compatibility surface may retain a longer legacy URL exactly as non-publishable audit data so existing REST read-to-write flows do not break; it cannot be published through V3 until it is shortened. A publishable CUSTOM tracker must include custom_event_name; strict V3 writes enforce that requirement. The V2 field remains optional so the original REST request shape can round-trip, but an unnamed custom event is recorded as non-publishable in its mapping artifact. The compiler bounds apply before translation so malformed tags cannot amplify their mapping artifacts. Strict V3 macro translation fails closed when a token is unknown or ambiguous. The V2 REST compatibility surface continues to accept its original safe-URL shape; an unresolved token is retained exactly and its mapping artifact is marked non-publishable rather than guessed. For example, HappyDemics documents {{USER_ID}} as the mobile advertising device identifier, so a tracker explicitly identified as HappyDemics maps that token to {DEVICE_ID}. The same token without vendor documentation is not guessed. Vendor-specific consent tokens such as ${GDPR_CONSENT_4594} canonicalize to {GDPR_CONSENT}. Follow-up delivery-adapter work will expand the canonical value into the consent syntax required by its upstream platform. Automatic translations come from a versioned macro registry keyed by source dialect and, where available, an exact documented tracker origin. A registry entry records the vendor, source token, canonical AdCP meaning, official documentation, date checked, confidence, and runtime constraints. Only verified entries are eligible for automatic translation. Unknown dialects and generic tokens such as {{USER_ID}} remain unresolved until the buyer identifies the vendor or confirms whether the value is a device advertising ID, browser identifier, platform account ID, or something else. The mapping artifact names the registry entry and version used so a later preview or audit can reproduce the decision. Use the V3 test_creative_macros read-only tool to inspect a tracker before it is saved or rendered. It runs the same canonical compiler used by tracking configuration, then uses the AdCP SDK to produce recipient syntax and an RFC-3986-encoded synthetic substitution. Reports keep raw, canonical, recipient, and substituted forms separate and fail closed on unresolved required macros. The built-in scenarios cover present and unavailable device IDs, GDPR with consent, non-GDPR traffic, and a missing required value. Supplied test bindings are labeled provided; built-in values are labeled synthetic or privacy_suppressed, and no real advertising identifier should be passed to the tool.

Effective impression trackers are attached when a display or HTML creative syncs to a seller and the creative has a tracker slot or HTML to carry them. Video (VAST) creatives and other tracker types are not attached yet, and rendered preview is separate follow-up work. Headless macro testing is available for every tracker.

Google Ad Manager sellers

When a seller serves through Google Ad Manager (GAM), Apostra converts each AdCP macro in an impression tracker to GAM’s own macro before sending it, and GAM fills the value when the ad serves. Each conversion comes from Google’s macro reference.

AdCP macro	GAM macro	Limits
`{CACHEBUSTER}`	`%%CACHEBUSTER%%`	None
`{DEVICE_ID}`	`%%ADVERTISING_IDENTIFIER_PLAIN%%`	Empty in child-directed apps and when limited ad tracking is on
`{DEVICE_ID_TYPE}`	`%%ADVERTISING_IDENTIFIER_TYPE%%`	As for `{DEVICE_ID}`
`{LIMIT_AD_TRACKING}`	`%%ADVERTISING_IDENTIFIER_IS_LAT%%`	None
`{GDPR}`	`${GDPR}`	None
`{GDPR_CONSENT}`	`${GDPR_CONSENT_<vendor ID>}`	Empty without a valid consent string. The tracker needs its IAB vendor ID; without one, Apostra removes the consent parameter
`{DOMAIN}`	`%%SITE%%`	Empty when the ad request carries no page URL, and on anonymous Ad Exchange ads
`{PAGE_URL}`	`%%PATTERN:url%%`	Empty when the ad request carries no page URL
`{APP_BUNDLE}`	`%%TAG_PARAM:msid%%`	Google documents it only for video ad requests, where its video SDK sends the app ID on every platform except iOS and tvOS. Expect it empty on web pages and display ads
`{AXEM}`	`%%PATTERN:axem%%`	Empty on pages that do not run the Scope3 Prebid module

Apostra fills {MEDIA_BUY_ID}, {CREATIVE_ID}, {CAMPAIGN_ID}, and {PACKAGE_ID} itself before sync. A tracker that uses any other macro is not sent to a GAM seller, because GAM has no equivalent. A tracker that uses {CLICK_URL} is not sent either: Google counts a click every time a pixel carrying its click macro loads, then discards those clicks as invalid. Run test_creative_macros with targetDialect: gam to see the conversion for a tracker before you save it.

A campaign override changes whether an inherited tracker fires; it does not mutate the advertiser tracker. Return the original tracker_id when updating a tracker so its campaign overrides and audit history remain attached. Send the last-read revision as expected_revision for advertiser updates, or campaign_revision as expected_revision for campaign updates, to reject a concurrent write instead of overwriting it.

On the V3 MCP surface, this model is projected as the tracking field on the existing advertiser and campaign nouns rather than as a separate tracker noun. Use save_advertiser({ advertiserId, tracking }) for advertiser defaults, save_campaign({ campaignId, tracking }) for campaign-local trackers and inherited overrides, and get(..., include: ["tracking"]) to read the result. V3 uses camel-case names such as trackerId, canonicalUrl, and effectiveTrackers. A tracker reads back its url as you saved it, beside the translated canonicalUrl; custom trackers use customEventName. Stored free-form values returned to a model—including tracker labels, raw and canonical URLs, custom event names, custom-macro descriptions, and mapping-artifact strings—are bounded and fenced as untrusted data. The V2 REST compatibility surface retains its snake-case field names and its prior unbounded description shape. V3 accepts new or changed custom-macro descriptions up to 240 characters; longer values stored through V2 are bounded in model output and can be saved unchanged so legacy configurations remain round-trip safe.

Click-URL parameters

Click-URL parameters are query parameters Apostra appends to a creative’s click-through URL when the creative is synced to a seller. They are one system with three layers, and every read and write surface sees the same rows:

Layer	Set through	Wins over
Advertiser	v2 `utmConfig` on the advertiser, or V3 `save_advertiser` `tracking.macroAdditions`	—
Campaign	v2 `utmConfig` on the campaign, or V3 `save_campaign` `tracking.macroAdditions`	Advertiser, for the same key
Creative	V3 `save_creative` `macroAdditions`	Campaign and advertiser, for the same key

Rules:

No defaults. A new advertiser has no parameters until you set them. Advertisers created before September 2026 carry the six utm_* entries Apostra used to apply on their behalf (utm_source=scope3, utm_medium=agentic, utm_campaign={CAMPAIGN_ID}, utm_content={CREATIVE_ID}, utm_media_buy={MEDIA_BUY_ID}, utm_package={PACKAGE_ID}); edit or clear them like any other entry.
At most 50 entries per layer. A write that would leave a layer with more than 50 keys is rejected; remove keys or replace the set. The v2 advertiser utmConfig field accepts at most 20 entries per request. Advertisers migrated in September 2026 were ported in key order up to that cap.
Suppression. Through V3, a null value removes an inherited key at that layer. The v2 utmConfig projection omits suppressed keys.
The authored URL wins. A key the click-through URL already carries is never overwritten by a parameter. When you create or update a creative whose click-through URL already sets a key that one of these parameters also sets, the response’s warnings array names each such key and the layer that set it (v2 creative create and update, and V3 save_creative). The creative is still saved. Remove the key from the click-through URL if you want the configured parameter instead.
Macros. A value may be a literal, or carry any AdCP universal macro as a {MACRO} token, for example utm_content={CREATIVE_ID}_{DOMAIN}{APP_BUNDLE}. {CAMPAIGN_ID} and a few older Apostra names such as {TACTIC_ID} are also accepted. Any other name in braces, and template syntax such as {{...}} or ${...}, is rejected.
Identity macros are filled when the creative syncs. Apostra fills {MEDIA_BUY_ID}, {CREATIVE_ID}, {CAMPAIGN_ID}, and {PACKAGE_ID} with its own ids. A parameter whose identity macro has no value for that sync is left off the click URL, so a seller never receives a placeholder for an id only Apostra knows. {PACKAGE_ID} has a value only when the creative is assigned to exactly one package of the media buy.
Other macros are filled per impression or click, not at sync. Values such as {DOMAIN}, {APP_BUNDLE}, {PAGE_URL}, and {CACHEBUSTER} are only known when the ad serves, so they stay in the click URL as {MACRO} tokens. The seller’s ad server fills them on Apostra’s click tracker, and Apostra’s click redirect copies each filled value into your landing page URL and removes any token it cannot fill, so a click through the tracker never lands on a literal token. Whether a seller fills a given macro is up to that seller; an unfilled one is left out. If a creative reaches the seller without Apostra’s click tracker, only the seller’s ad server can fill these macros, and any it leaves unfilled reach the landing page as written. That happens when the advertiser has turned click tracking off (v2 click_tracker_enabled, V3 tracking.clickTrackerEnabled): Apostra then sends the click-through URL without its click tracker, on a campaign-level sync and with a media buy alike, and still fills the identity macros above. Turning click tracking off covers the click tracker Apostra adds when a creative syncs; a click tracker generated when the creative was created, while click tracking was on, can still reach the seller. The older Apostra names such as {TACTIC_ID} are never filled in a click URL, so a parameter carrying one is always left off.
Keys start with a letter or digit and use URL query-key characters (max 100).
A change re-syncs affected creatives automatically. When an advertiser or campaign parameter change alters the click URL of a creative that a seller already holds on a live media buy, Apostra re-sends that creative to that seller with the new parameters, once per media buy so each copy keeps its own identity macros. A live media buy is one that has been submitted and has not completed, been canceled, failed, or been rejected. The re-sync starts about a minute after the change, and further edits in that minute join it, so a burst of edits sends each creative to each seller once. A creative whose click URL comes out the same, for example because the campaign or the creative itself sets the changed key, is not re-sent. The write’s response carries creativeResync (creative_resync on the tracking-config resources) with how many creatives and sellers the re-sync covers; it is absent when nothing a seller holds changes. Each seller decides whether a changed click URL needs re-review, and its decision appears on the creative the same way it does after a creative edit. The copy the seller already has keeps serving until the seller says otherwise. If a seller has not yet reported its review of an earlier copy of the same creative, Apostra waits for that review to finish, up to seven days after that copy was sent, and then sends the change.

How v2 `utmConfig` writes differ by layer

The v2 utmConfig field has a different write shape at each layer:

Layer	v2 write shape	What a write does
Advertiser	An array of `{ paramKey, paramValue }`	Replaces the advertiser’s whole set. `[]` clears it; omitting the field leaves it unchanged
Campaign	An object: `params` plus optional `deleteMissing`	Adds or updates the listed keys and keeps the campaign’s other keys. `deleteMissing: true` replaces the campaign’s whole set
Creative	Not available in v2	—

So the same entries have different effects at each layer. Sent as the advertiser array, any advertiser keys you leave out are removed. Sent as a campaign’s params, the campaign keys you leave out stay unless you set deleteMissing: true. v2 also cannot remove an inherited key at a lower layer: a campaign can only override an advertiser key with a different value. Use V3 macroAdditions for per-layer control. V3 has one model at all three layers: save_advertiser and save_campaign take tracking.macroAdditions, and save_creative takes macroAdditions. Each is a list of { paramKey, value } that sets that layer’s whole list, and a null value suppresses an inherited key at that layer. Both versions read and write the same stored parameters, so you can move a buyer to V3 without migrating data.

Lifecycle

Create the advertiser

For a live advertiser, confirm the buyer operator identity, then provide name, brand domain, required currency, sandbox mode, and optional channel preferences. Sandbox advertisers can be created before that identity is claimed, but plan and Terms readiness still apply. Sandbox is locked after creation.

Configure defaults

Update channel preferences, optimizationApplyMode, UTM params, and frequency caps as policy evolves. Channel overlap affects automatic seller qualification without creating advertiser-owned selection edges.

Run campaigns

Create campaigns under the advertiser. Discovery, audiences, and creatives are scoped to this advertiser.

Archive when done

DELETE /api/v2/buyer/advertisers/:id archives the advertiser (soft delete). Use POST /api/v2/buyer/advertisers/:id/restore to bring it back.

Common operations

Before creating an advertiser from a domain, buyer MCP clients can call the side-effect-free resolve_buyer_brand operation to show the brand-confirmation card. The call is a quick preview: it answers within about 8 seconds, and if the brand can’t be read in that time it returns resolved: false with pending: true for the domain, which means the brand isn’t known yet, not that none exists. A card without pending and resolved: false is a domain with no registered brand. A repeat call a little later, or for a domain looked up in the last ten minutes, is usually answered from what the first call found. The user then confirms by creating the advertiser normally; creating reads the brand in full, so a slow or skipped preview doesn’t change what is saved.

Create an advertiser

curl -X POST https://api.apostra.com/api/v2/buyer/advertisers \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "description": "Acme global advertiser account",
    "brand": "acme.com",
    "primaryCurrency": "USD",
    "channels": ["display", "ctv"],
    "optimizationApplyMode": "MANUAL",
    "sandbox": false
  }'

{
  "name": "Acme Corp",
  "brand": "acme.com",
  "primaryCurrency": "USD",
  "channels": ["display"],
  "optimizationApplyMode": "MANUAL",
  "linkedAccounts": [
    {
      "storefrontId": 1,
      "sourceId": "src_main",
      "accountId": "acc_67890",
      "credentialId": "cred_snap_coke",
      "billingType": "brand"
    }
  ],
  "frequencyCaps": [
    { "max_impressions": 3, "window": { "interval": 7, "unit": "days" } }
  ]
}

Get / list advertisers

# List active advertisers (summary rows)
curl "https://api.apostra.com/api/v2/buyer/advertisers?status=ACTIVE&limit=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

# Search by partial name or advertiser ID (search runs before pagination)
curl "https://api.apostra.com/api/v2/buyer/advertisers?status=ACTIVE&search=12345&limit=20" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

# Get a single advertiser (full resource — linkedBrand, linkedAccounts, utmConfig, frequencyCaps)
curl https://api.apostra.com/api/v2/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

List rows return the summary shape — id, name, status, sandbox, brand, linkedAccountCount, createdAt, updatedAt. Call GET /api/v2/buyer/advertisers/:id for the full resource (resolved brand object, full linked-account list, UTM config, frequency caps).

List response

{
  "items": [
    {
      "id": "12345",
      "name": "Acme Corp",
      "status": "ACTIVE",
      "sandbox": false,
      "brand": "acme.com",
      "linkedAccountCount": 3,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-20T14:45:00Z"
    }
  ],
  "total": 1,
  "hasMore": false,
  "nextOffset": null
}

List supports filtering by status, name (case-insensitive partial name match), search (partial name or advertiser ID), and sandbox (true/false), plus limit and offset pagination. Filters, including search, are applied before pagination.

Update an advertiser

curl -X PUT https://api.apostra.com/api/v2/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "channels": ["display", "olv", "ctv"],
    "optimizationApplyMode": "AUTO",
    "frequencyCaps": [
      { "max_impressions": 5, "window": { "interval": 7, "unit": "days" } }
    ]
  }'

Through the raw v2 API, brand domain, an already-known country scope, currency, and reporting time zone can be re-keyed only before the first campaign or seller-account binding. A still-unknown legacy country scope may be classified once after first use. The canonical UI exposes that one-time classification but not edits to known brand, country, or currency values; create another advertiser there when known identity values must differ. sandbox is always immutable. When frequencyCaps or channels is provided on update, it replaces the existing set. Pass an empty array to clear; omit the field to leave it untouched.

For a legacy advertiser that has no settings row, mixed currencies across terminal (completed, cancelled, or archived) campaigns do not require a replacement advertiser. When adding its brand, send primaryCurrency with the intended currency from that history. Active campaigns and currently linked seller accounts still take precedence and reject conflicting choices.

Archive / restore

curl -X DELETE https://api.apostra.com/api/v2/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl -X POST https://api.apostra.com/api/v2/buyer/advertisers/12345/restore \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Archiving is a soft delete with these semantics:

Children stay readable. The advertiser’s campaigns, media buys, and creatives are retained and can still be listed and read while the advertiser is archived. Writes that would change them are still refused until the advertiser is restored.
The name is released. Name uniqueness applies to active advertisers only, so a new advertiser may reuse an archived advertiser’s name.
A sandbox advertiser’s brand identity is released. A new sandbox advertiser may take an archived sandbox advertiser’s brand identity (brand domain, brand ID, countries, and currency). A non-sandbox advertiser’s brand identity stays reserved while it is archived.
Restore can conflict. Restoring an advertiser returns 409 CONFLICT when an active advertiser now holds its name, or, for a sandbox advertiser, its brand identity. The brand identity conflict has reason: brand_identity_exists and the advertiserId of the active sandbox advertiser. Only one active sandbox advertiser can hold a brand identity, so archive that advertiser (or rename the other, for a name conflict) before restoring.
Restore reopens ledger accounts. The advertiser’s archived ledger accounts are reopened as part of the restore.

From the v3 agent surface, save_advertiser performs the same operations with isArchived: true / false, and accepts advertiserIds to archive or restore several advertisers in one call.

Linked accounts

The linkedAccounts field connects the advertiser to existing accounts on upstream platforms — Snap, programmatic DSPs, agency seats. Each linked account is the pre-existing seat ID a partner already has for this brand or buyer; the link makes that ID addressable to Apostra for cross-platform reporting and pass-through execution.

Use linkedAccounts whenever the buyer already has a relationship with the upstream platform — an existing Snap seat, a DV360/Trade Desk account, an agency-managed seat. Linked accounts let Apostra reuse the seat ID for unified reporting and pass-through execution without re-provisioning credentials per call. This account choice is independent of campaign mode, BYOA, protocol connectivity, and settlement; do not infer those from routingType.

Fields

Each link maps these fields:

Field	Type	Notes
`storefrontId`	integer	Storefront the source lives on. Get from `GET /api/v2/buyer/storefronts`.
`sourceId`	string	Inventory source within `storefrontId` whose account is being linked.
`accountId`	string	The seller-issued AdCP/source account ID (e.g. `acc_67890`). Must come from account discovery — Apostra does not mint it and clients must not substitute the internal `linkId`.
`credentialId`	string \| null	The connected provider credential that owns this linked account. Include it when creating or updating links if multiple credentials can expose the same `accountId`.
`billingType`	string (optional)	The billing arrangement for this link. Defaults to the source’s default billing type when omitted.

billingType is a source-defined string. The supported values per source are reported on the discovery endpoint (GET /api/v2/buyer/advertisers/:advertiserId/accounts/available?storefrontId=...&sourceId=... returns billingOptions.supported and billingOptions.default). Common values:

Value	Meaning
`brand`	The advertiser is billed directly by the partner
`agency`	An agency is the billing entity acting on behalf of the brand

Other values may be supported by individual partners — always check billingOptions.supported before sending.

Endpoints

Method	Path	Purpose
`GET`	`/api/v2/buyer/advertisers/:advertiserId/accounts`	List linked accounts on the advertiser
`GET`	`/api/v2/buyer/advertisers/:advertiserId/accounts/available`	List accounts the source has discovered but not yet linked
`GET`	`/api/v2/buyer/advertisers/:advertiserId/accounts/:accountId`	Get a single linked account
`POST`	`/api/v2/buyer/advertisers/:advertiserId/accounts`	Link a source account to the advertiser

List linked accounts

curl "https://api.apostra.com/api/v2/buyer/advertisers/12345/accounts?storefrontId=1&sourceId=src_main&status=active&take=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Filters: storefrontId + sourceId (must be paired), status (active, pending_approval, payment_required, suspended, closed). Pagination: take, skip.

Response

{
  "data": {
    "accounts": [
      {
        "linkId": "42",
        "accountId": "acc_67890",
        "credentialId": "cred_snap_coke",
        "name": "Acme c/o Pinnacle",
        "sources": [
          {
            "storefrontId": 1,
            "storefrontName": "Retail Media Network",
            "sourceId": "src_main",
            "sourceName": "Retail Network Agent"
          }
        ],
        "advertiserId": "12345",
        "billing": "brand",
        "status": "active",
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-20T14:45:00Z"
      }
    ],
    "total": 1
  }
}

Link an account

curl -X POST https://api.apostra.com/api/v2/buyer/advertisers/12345/accounts \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storefrontId": 1,
    "sourceId": "src_main",
    "accountId": "acc_67890",
    "billingType": "brand"
  }'

The response carries the full AccountOutput with the server-assigned linkId. To pre-fill the request body, call GET /accounts/available?storefrontId=1&sourceId=src_main first — it returns every discovered account with its supported billingOptions.

Get a single linked account

curl https://api.apostra.com/api/v2/buyer/advertisers/12345/accounts/acc_67890 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Returns the same AccountOutput shape as list. Use this to confirm a link’s current status after a source-side state change (e.g. moving from pending_approval to active).

Linked accounts surface external account IDs (e.g. acc_67890) so cross-platform reporting and pass-through execution can target them without re-discovering credentials. The linkId is Apostra-side primary key for the link itself; the accountId is the source-side account.

Sandbox advertisers

Set sandbox: true at creation to mark the advertiser as test-only. All ADCP operations under sandbox advertisers — discovery, media buy creation, execution — route to sandbox-flagged sales agent accounts. No real platform calls are made and no real spend occurs. You can create, update, and archive a sandbox advertiser before claiming the buyer operator identity, on every surface. Plan and Terms readiness checks still apply; this exemption is only for the operator-identity check. Use sandbox advertisers to:

Rehearse the discovery → execute → report flow end-to-end
Test creative manifest workflows without notifying publishers
Train AI agents against the API without billing implications

Optimization apply mode

optimizationApplyMode controls whether Apostra’s RL optimizer applies suggestions to media buys automatically.

MANUAL (default) — suggestions appear in the suggestion feed; a human or agent must approve before they hit media buys
AUTO — suggestions are applied immediately

The advertiser-level setting is the default for campaigns under the advertiser. Each campaign can override it.

Campaign

Marketing initiatives owned by the advertiser

Brand

Brand identity resolved from AdCP registry or /.well-known/brand.json

Frequency caps

Buyer-side caps enforced by Apostra across publishers

Creatives

Manifest-based creatives nested under campaigns

Start here

Buy media

Sell media

Help and updates

Overview

Media Company-managed advertisers

Why advertisers matter

Key fields

Organization roster projection

Seller-managed advertiser viewer access

Confirming markets and channels with your agent

Summary shape (list rows)

Full shape (single advertiser)

Brand resolution

Uniqueness

Sub-resources

Tracker defaults and campaign inheritance

Google Ad Manager sellers

Click-URL parameters

How v2 `utmConfig` writes differ by layer

Lifecycle

Common operations

Create an advertiser

Get / list advertisers

Update an advertiser

Archive / restore

Linked accounts

Fields

Endpoints

List linked accounts

Link an account

Get a single linked account

Sandbox advertisers

Optimization apply mode

Campaign

Brand

Frequency caps

Creatives

​Overview

​Media Company-managed advertisers

​Why advertisers matter

​Key fields

​Organization roster projection

​Seller-managed advertiser viewer access

​Confirming markets and channels with your agent

​Summary shape (list rows)

​Full shape (single advertiser)

​Brand resolution

​Uniqueness

​Sub-resources

​Tracker defaults and campaign inheritance

​Google Ad Manager sellers

​Click-URL parameters

​How v2 utmConfig writes differ by layer

​Lifecycle

​Common operations

​Create an advertiser

​Get / list advertisers

​Update an advertiser

​Archive / restore

​Linked accounts

​Fields

​Endpoints

​List linked accounts

​Link an account

​Get a single linked account

​Sandbox advertisers

​Optimization apply mode

​Related concepts

Campaign

Brand

Frequency caps

Creatives

Overview

Media Company-managed advertisers

Why advertisers matter

Key fields

Organization roster projection

Seller-managed advertiser viewer access

Confirming markets and channels with your agent

Summary shape (list rows)

Full shape (single advertiser)

Brand resolution

Uniqueness

Sub-resources

Tracker defaults and campaign inheritance

Google Ad Manager sellers

Click-URL parameters

How v2 `utmConfig` writes differ by layer

Lifecycle

Common operations

Create an advertiser

Get / list advertisers

Update an advertiser

Archive / restore

Linked accounts

Fields

Endpoints

List linked accounts

Link an account

Get a single linked account

Sandbox advertisers

Optimization apply mode

Related concepts