Update advertiser

PUT /api/v2/buyer/advertisers/{advertiserId} Updates an existing advertiser through the raw v2 API. All body fields are optional — send only what you want to change. Brand domain, an already-known country scope, currency, and reporting time zone can change only before the first campaign or seller-account binding. A legacy advertiser whose country scope is still unknown may classify it once even after first use. sandbox is fixed at creation.

In the app

In Apostra, advertiser settings open as one Task titled Advertiser settings. Open it from Settings on an advertiser’s row on the Advertisers Page, from the pencil beside the advertiser in the left rail, or from Edit advertiser under Settings → Setup & readiness. An agent opens it with open_add_advertiser and the advertiser’s advertiserId. The Task lets you change the name, description, channels, and, until the advertiser has a campaign or linked seller account, the reporting time zone. The brand domain, countries, currency, and environment show as read-only, each with a short reason. Until the advertiser has a campaign or linked seller account, the brand domain, countries and currency can still be changed through this endpoint or an agent; after that they are fixed. The environment is fixed when the advertiser is created. Save changes saves the advertiser, opens the Advertisers Page, and closes the Task. Cancel closes it without saving. If the Advertisers Page can’t open, the Task stays open with the error and a Done button. Once the Task closes, it doesn’t come back when you reopen that chat. Creating an advertiser works the same way, except the confirmation stays open so you can switch into the new advertiser or add another, until you choose Done. Buyer-owned labels are managed separately through V3 MCP save_advertiser, not this REST endpoint. See Dimensions and labels.

Request

curl

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" } }
    ]
  }'

Parameters

Field	Type	Required	Notes
`advertiserId`	string (path)	Yes	Unique identifier for the advertiser
`name`	string	No	Updated name (1–255 chars)
`description`	string	No	Updated description (max 1000 chars)
`brand`	string	No	Brand domain. Can be re-keyed only before the first campaign or seller-account binding
`brandCountries`	array	No	BrandKey country scope. Pass `[]` to confirm that the advertiser works in all countries. An unknown legacy scope may be classified once after first use; changing an already-known scope is locked after the first campaign or seller-account binding
`optimizationApplyMode`	enum	No	`AUTO` or `MANUAL`
`primaryCurrency`	string	No	ISO 4217 currency. Can be re-keyed only before the first campaign or seller-account binding
`preferredTimezone`	string	No	Preferred IANA Reporting time zone. Seller-effective time zones can differ; changeable until the first campaign or seller-account binding
`channels`	array	No	Replaces the editable AdCP channel preferences. Pass `[]` to clear. Channel overlap affects automatic seller qualification but does not create advertiser-owned selection edges
`linkedAccounts`	array	No	Accounts to add. Existing links are not removed. Each item may include `credentialId` from list available accounts to disambiguate duplicate account IDs across connected credentials
`utmConfig`	array	No	Replaces all advertiser-level click-URL parameters (max 20). Pass `[]` to clear. Unlike campaign `utmConfig`, there is no additive mode; see How v2 `utmConfig` writes differ by layer
`dataDelivery`	object	No	Data-delivery configuration. Omit to leave existing config untouched
`dataDelivery.credentials`	array	No	Replaces all existing live credentials. Pass `[]` to archive all
`dataDelivery.outputs`	array	No	Replaces all existing advertiser-scoped Data Delivery Outputs. Pass `[]` to clear
`frequencyCaps`	array	No	Replaces all existing non-archived caps. Pass `[]` to clear; omit to leave untouched

Response

{
  "id": "12345",
  "name": "Acme Corporation",
  "description": null,
  "status": "ACTIVE",
  "sandbox": false,
  "optimizationApplyMode": "AUTO",
  "primaryCurrency": "USD",
  "brandCountries": ["DE", "NL"],
  "brandCountriesKnown": true,
  "preferredTimezone": "Europe/Amsterdam",
  "currencyLocked": true,
  "reportingTimezoneLocked": true,
  "channels": ["display", "olv", "ctv"],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-20T14:45:00Z",
  "brand": "acme.com",
  "linkedAccounts": [],
  "utmConfig": [],
  "frequencyCaps": []
}

Returns the full advertiser resource with the applied changes. brandCountriesKnown: true confirms that brandCountries is authoritative. An empty authoritative list is global, not a scope with zero countries. A legacy advertiser may return brandCountriesKnown: false with an empty list; setting brandCountries classifies that scope once, even after first use.

linkedAccounts is additive (existing links stay), but utmConfig and frequencyCaps replace their entire existing set. Pass an empty array to clear, or omit the field to leave it untouched.

If a legacy advertiser has no settings row and its terminal (completed, cancelled, or archived) campaign history spans currencies, include primaryCurrency with the intended currency when you add its brand. The value must match one of the historical campaign currencies. Active campaigns and currently linked seller accounts remain authoritative and still block conflicting currency choices; do not create a duplicate advertiser to bypass that conflict.

Errors

400 VALIDATION_ERROR — invalid field value.
409 CONFLICT — brand domain, an already-known country scope, currency, or reporting time zone is changed after the first campaign or seller-account binding, or legacy currency evidence cannot be resolved safely. Classifying a still-unknown legacy country scope is the one country-scope exception.
404 NOT_FOUND — advertiserId does not exist or is not visible to the authenticated account.

See Errors for the full error contract.

The canonical UI keeps brand, an already-known country scope, and currency out of the edit form. It offers a one-time country classification for a legacy advertiser whose scope is still unknown. Create another advertiser from the UI when known identity values must differ.

Advertiser tasks

All advertiser operations

Advertiser overview

Fields, lifecycle, and concepts

Get advertiser

Read the current state first

Delete advertiser

Archive when done

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Update advertiser

In the app

Request

Parameters

Response

Errors

Advertiser tasks

Advertiser overview

Get advertiser

Delete advertiser

​In the app

​Request

​Parameters

​Response

​Errors

​Related

Advertiser tasks

Advertiser overview

Get advertiser

Delete advertiser

In the app

Request

Parameters

Response

Errors

Related