PUT /api/v2/buyer/advertisers/{advertiserId}/catalogs/{catalogId}/transform
Saves the active transform for a catalog: a deterministic rule set that maps raw feed items into campaign groups, budget hints, and creative-asset prompts. Saving a new transform archives the previous active one — a catalog has exactly one active transform at a time.
How catalog activation works
A transform has three parts, applied in order:- Derived fields (
transform.fields) — compute new fields from raw item data. Each field pulls from asourcedot-path (e.g.location.city), atemplateof{{field}}placeholders, or adefault, and can be normalized with atransformsuch asslugortitle_case. Derived fields feed the grouping and template rules below. - Campaign grouping and budget (
transform.campaign) — fan the items out into campaign groups.groupBynames the fields to group on (usually derived fields such ascity);nameTemplate/keyTemplatelabel each group;budgetsets a spend hint per group. - Creative-asset prompts (
transform.creativeAssets) — define reusable creative generation prompts. Each entry has apromptTemplate, akeyTemplatecache key (assets sharing a key reuse generated media), and an optionalgroupByto fan out unique prompts.
- Save transform (this operation) — persist the active transform.
- Preview activation — dry-run the plan to see exactly what would be created, or pass
save: trueto persist it. - Execute activation — materialize the plan into campaign, creative-generation, and seller-syndication jobs.
- Refresh catalog — pull the latest feed and, optionally, re-run activation.
city, is transformed with a derived city field, campaign.groupBy: ["city"], and nameTemplate: "Acme - {{city}}". Preview fans the 6 items out into 3 campaign groups — Acme - Austin, Acme - Denver, Acme - Portland — each with 2 items.
You can build and run the whole flow in the UI under Data sources → Catalogs (Preview activation, Refresh feed, Refresh and activate).
Request
curl
Parameters
Each
fields[] entry must define at least one of source, template, or default.
Budget rule (transform.campaign.budget) is a tagged union on mode:
Response
active; the previously active transform (if any) is set to archived.
Errors
400 VALIDATION_ERROR— the transform fails schema validation (e.g. afields[]entry defines none ofsource/template/default, orcampaign.groupByis empty).404 NOT_FOUND—advertiserIdorcatalogIddoes not exist or is not visible to the authenticated account.
Related
Preview activation
Dry-run the campaign/creative fan-out
Execute activation
Materialize the plan into jobs
Refresh catalog
Pull the latest feed and re-activate
Sync catalogs
Push catalog feeds and items