> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinterest Ads adapter compatibility

> Exact AdCP-to-Pinterest Ads mapping, implemented coverage, proof state, and known limits.

Pinterest Ads maps AdCP media buys to campaigns, packages to ad groups, and creative assignments to ads backed by Pins. Current code classifies seven product families as executable through deterministic contract coverage; this is not fresh provider eligibility. Catalog sales and Idea Pins remain explicitly blocked.

<Note>
  **Review-ready, not provider-endorsed · last verified 2026-08-16.**
  This is an Interchange compatibility review prepared for partner feedback. Pinterest has not reviewed, certified, or endorsed it. “Implemented” means a provider write/read path exists.
  It does not mean fresh signed live evidence exists or that the selected account
  is currently eligible.
</Note>

## Coverage and execution-package model

| Layer                         | State                                     | Current contract                                                                                                                                                                                             |
| ----------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Provider-observed denominator | `not_certified`                           | The nine classified rows are an implemented and blocked execution catalog, not a certified complete inventory of every Pinterest Ads creation path.                                                          |
| Wholesale product archetype   | `classified`                              | Product rows represent materially different launch contracts. Signals, activation resources, targeting and delivery overlays, and creative choices do not create extra product rows.                         |
| Exact execution package       | `exact_static_base_plus_runtime_bindings` | Each product ID fixes the provider objective, optimization, promotion type, and billing tuple; Pins, conversion tags, audiences, catalogs, targeting, budget, bid, and flight are separate runtime bindings. |
| Current account eligibility   | `account_check_required`                  | Ad-account permissions, objective eligibility, resource readiness, market, and exact Pin support determine whether an implemented product is runnable now.                                                   |

## Claim provenance gaps

Object-mapping and reporting rows have no exported, code-owned complete
denominator on current main. They remain published because they are useful,
but the contract marks the missing drift oracle instead of pretending a
same-test literal prevents drift.

| Claim family      | State                            | Drift enforced | Trace sources                                                                                    | Gap                                                                                             |
| ----------------- | -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `object_mappings` | `manual_plan_trace_non_enforced` | `false`        | packages/storefront-adapters/src/platforms/pinterest/adapter.ts, docs/adapter-plans/pinterest.md | No code-owned complete object-mapping denominator exists; these rows remain manually traced.    |
| `reporting`       | `manual_plan_trace_non_enforced` | `false`        | packages/storefront-adapters/src/platforms/pinterest/tasks/media-buy/get-media-buy-delivery.ts   | No exported code-owned reporting projection constant exists; these rows are not drift-enforced. |

## Evidence state

Static certification and live certification are different claims. Deterministic
tests can prove code-owned catalog classifications and fail-closed behavior
without contacting the provider. Object-mapping and reporting rows are validated
for shape, presence, and uniqueness only; the provenance table above records that
they are not compared with a complete code-owned denominator.
Fresh live evidence must be dated, signed, bound to the exact account, product,
resources, fixture revision, requested package, readback, no-spend result, and
cleanup result. Live evidence is treated as stale after 30 days, and a newer
failure overrides an older pass.

| Layer                           | State                                      | Last verified | What it means                                                                                                                                                                                                     |
| ------------------------------- | ------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Static / deterministic contract | `contract_tested`                          | 2026-08-16    | All configured products are classified, and the current self-serve creative writers are tested against exact Pin identities.                                                                                      |
| Fresh signed live evidence      | `harness_ready_last_canonical_run_skipped` | —             | The protected harness is ready, but canonical GitHub Actions run 29671483671 skipped every Pinterest check because no dedicated staging account was configured. There is no current complete live provider proof. |
| AAO discovery                   | `community_catalog`                        | 2026-08-16    | The public record uses a broad Pinterest Feed discovery placement and is not publisher-owned authorization.                                                                                                       |

## Markets

**`account_check_required`.** No global market allowlist is asserted by this public contract.

This page publishes no global market allowlist.

Authority: The selected account's live provider eligibility and targeting reads are authoritative.

## Object mapping

| AdCP / Interchange    | Pinterest Ads               | Mapping                                                                       |
| --------------------- | --------------------------- | ----------------------------------------------------------------------------- |
| `account`             | `ad account`                | Explicit Pinterest ad account selected after OAuth.                           |
| `media_buy`           | `campaign`                  | Objective, intended promotion type, lifecycle, and budget cap.                |
| `package`             | `ad group`                  | Budget, bid, optimization, targeting, placement group, frequency, and flight. |
| `creative`            | `Pin`                       | Existing or adapter-published image/video Pin.                                |
| `creative_assignment` | `ad`                        | Ad binds a Pin to an ad group.                                                |
| `signal`              | `audience or interest node` | Account-owned audiences and provider taxonomy IDs.                            |

## Operations

| Public adapter operation | Surface                                                    | State                | Provider path                                                                                                                                                                                                                      |
| ------------------------ | ---------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_accounts`          | AdCP buyer operation                                       | `implemented`        | Authorized ad-account discovery                                                                                                                                                                                                    |
| `sync_accounts`          | AdCP buyer operation                                       | `not_implemented`    | Account synchronization is not implemented.                                                                                                                                                                                        |
| `get_products`           | AdCP buyer operation                                       | `implemented`        | Seven executable and two blocked product mappings                                                                                                                                                                                  |
| `sync_creatives`         | AdCP buyer operation                                       | `implemented`        | Pin ownership validation and self-serve Pin creation for executable formats                                                                                                                                                        |
| `list_creatives`         | AdCP buyer operation                                       | `implemented`        | Pin inventory and ad assignment projection                                                                                                                                                                                         |
| `create_media_buy`       | AdCP buyer operation                                       | `implemented`        | Campaign → ad group → ad                                                                                                                                                                                                           |
| `get_media_buys`         | AdCP buyer operation                                       | `implemented`        | Campaign hierarchy and targeting provenance                                                                                                                                                                                        |
| `update_media_buy`       | AdCP buyer operation                                       | `implemented`        | Lifecycle, budget, bid, geography, audiences, and creative assignment updates with readback                                                                                                                                        |
| `get_media_buy_delivery` | AdCP buyer operation                                       | `implemented`        | Campaign and ad-group analytics                                                                                                                                                                                                    |
| `analyze_account`        | Admin/ops introspection (not an AdCP buyer wire operation) | `implemented`        | Admin/ops introspection; not an AdCP buyer wire operation. Account readiness and optimization analysis                                                                                                                             |
| `get_signals`            | AdCP buyer operation                                       | `implemented`        | Audience and interest discovery                                                                                                                                                                                                    |
| `sync_audiences`         | AdCP buyer operation                                       | `activation_blocked` | Present internally but not publicly activated: the governed lifecycle declares inventory, creation, membership changes, durable identity, readiness, targeting, and deletion pending, with its canary blocked                      |
| `sync_event_sources`     | AdCP buyer operation                                       | `provider_limited`   | Returns a buyer-instrumented Pinterest Tag snippet and installation instructions; makes no Pinterest API call and emits no built-in provider event source                                                                          |
| `log_event`              | AdCP buyer operation                                       | `activation_blocked` | Not registered in public tools/list. A provider-authoritative guarded implementation remains internal until sync\_event\_sources can publish trusted selected-account/source bindings and a signed dedicated-account canary passes |
| `sync_catalogs`          | AdCP buyer operation                                       | `provider_limited`   | Registers a Pinterest catalog feed URL through POST /catalogs/feeds and the local store; inline item push is not implemented                                                                                                       |
| `get_account_financials` | AdCP buyer operation                                       | `provider_limited`   | Campaign spend aggregation is available; the v6 AccountStore variant returns UNSUPPORTED\_FEATURE pending context threading                                                                                                        |

## Wholesale products and exact execution bases

| Product ID                   | Exact provider execution base                                                                   | Implemented       | Static certification     | Current eligibility      | Known gap                         |
| ---------------------------- | ----------------------------------------------------------------------------------------------- | ----------------- | ------------------------ | ------------------------ | --------------------------------- |
| `pinterest_awareness`        | objective `AWARENESS`; optimization `AUTOMATIC_BID`; billing `IMPRESSION`                       | `implemented`     | `deterministic_contract` | `account_check_required` | —                                 |
| `pinterest_consideration`    | objective `CONSIDERATION`; optimization `clicks`; billing `CLICKTHROUGH`                        | `implemented`     | `deterministic_contract` | `account_check_required` | —                                 |
| `pinterest_video_views`      | objective `VIDEO_VIEW`; optimization `AUTOMATIC_BID`; billing `VIDEO_V_50_MRC`                  | `implemented`     | `deterministic_contract` | `account_check_required` | —                                 |
| `pinterest_conversions`      | objective `SALES / STANDARD_AD`; optimization `CHECKOUT`; billing `IMPRESSION`                  | `implemented`     | `deterministic_contract` | `account_check_required` | —                                 |
| `pinterest_leads`            | objective `LEADS / STANDARD_AD`; optimization `LEAD`; billing `IMPRESSION`                      | `implemented`     | `deterministic_contract` | `account_check_required` | —                                 |
| `pinterest_traffic`          | objective `WEB_SESSIONS`; optimization `clicks`; billing `CLICKTHROUGH`                         | `implemented`     | `deterministic_contract` | `account_check_required` | —                                 |
| `pinterest_performance_plus` | objective `SALES / STANDARD_AD`; optimization `CHECKOUT + auto targeting`; billing `IMPRESSION` | `implemented`     | `deterministic_contract` | `account_check_required` | —                                 |
| `pinterest_catalog_sales`    | objective `SALES / CATALOG`; optimization `CHECKOUT`; billing `IMPRESSION`                      | `not_implemented` | `not_certified`          | `not_eligible`           | catalog\_execution\_incomplete    |
| `pinterest_idea_pins`        | objective `AWARENESS`; optimization `AUTOMATIC_BID`; billing `IMPRESSION`                       | `not_implemented` | `not_certified`          | `not_eligible`           | creative\_round\_trip\_incomplete |

## Creative formats

The format state is deliberately narrower than the provider format catalog.
Only `executable` formats have the ordinary provider write and readback path;
`canary_only` formats are restricted to governed proof, and
`catalog_declared` formats are present in current code without a public
ordinary-execution certification claim.
`declared_not_buyer_selectable` formats are not sold through the adapter.

| Format ID                       | Kind             | State                           | Provider shape                    |
| ------------------------------- | ---------------- | ------------------------------- | --------------------------------- |
| `pinterest_existing_post`       | `native_in_feed` | `canary_only`                   | authorized existing Pin           |
| `pinterest_standard_pin`        | `image`          | `executable`                    | REGULAR image Pin                 |
| `pinterest_video_pin`           | `video_hosted`   | `executable`                    | VIDEO Pin                         |
| `pinterest_max_width_video`     | `video_hosted`   | `executable`                    | MAX\_VIDEO Pin                    |
| `pinterest_carousel`            | `image_carousel` | `declared_not_buyer_selectable` | CAROUSEL Pin                      |
| `pinterest_collection`          | `image_carousel` | `declared_not_buyer_selectable` | COLLECTION Pin                    |
| `pinterest_idea_pin`            | `image_carousel` | `declared_not_buyer_selectable` | IDEA Pin                          |
| `pinterest_showcase`            | `image_carousel` | `declared_not_buyer_selectable` | SHOWCASE Pin                      |
| `pinterest_quiz`                | `image_carousel` | `declared_not_buyer_selectable` | QUIZ Pin                          |
| `pinterest_promoted_offerings`  | `image`          | `declared_not_buyer_selectable` | one ad group and Pin per offering |
| `pinterest_generated_image_2x3` | `native_in_feed` | `declared_not_buyer_selectable` | generated 2:3 Pin image           |
| `pinterest_generated_video`     | `video_hosted`   | `declared_not_buyer_selectable` | generated vertical Pin video      |
| `pinterest_generated_offerings` | `native_in_feed` | `declared_not_buyer_selectable` | generated Pin per offering        |

## Placements

| Placement ID     | Surface        | State              | Provider mapping                                                                |
| ---------------- | -------------- | ------------------ | ------------------------------------------------------------------------------- |
| `pinterest_feed` | Pinterest Feed | `provider_limited` | AAO discovery umbrella; executable products currently send placement\_group ALL |

## Targeting

| AdCP dimension     | State                | Provider mapping                                                                                    |
| ------------------ | -------------------- | --------------------------------------------------------------------------------------------------- |
| `geo_countries`    | `implemented`        | targeting\_spec.LOCATION                                                                            |
| `geo_regions`      | `implemented`        | ISO subdivision → targeting\_spec.GEO with provenance                                               |
| `audience_include` | `activation_blocked` | Not publicly activated while the governed audience lifecycle and targeting authority remain pending |
| `audience_exclude` | `activation_blocked` | Not publicly activated while the governed audience lifecycle and targeting authority remain pending |
| `signals`          | `implemented`        | targeting\_spec.INTEREST after taxonomy resolution                                                  |
| `frequency_cap`    | `implemented`        | lifetime\_frequency\_cap                                                                            |
| `placement_refs`   | `provider_limited`   | No per-placement AdCP selection; ad groups currently use placement\_group ALL                       |

## Reporting

| AdCP output       | Provider source                         | Notes                                               |
| ----------------- | --------------------------------------- | --------------------------------------------------- |
| `impressions`     | `TOTAL_IMPRESSION`                      | Campaign and ad-group totals                        |
| `clicks`          | `TOTAL_CLICKTHROUGH`                    | Campaign and ad-group totals                        |
| `spend`           | `SPEND_IN_MICRO_DOLLAR`                 | Provider micro-currency converted exactly           |
| `ctr`             | `TOTAL_CLICKTHROUGH / TOTAL_IMPRESSION` | Calculated from raw provider values                 |
| `views`           | `TOTAL_VIDEO_MRC_VIEWS`                 | Video-view campaigns                                |
| `by_package`      | `ad-group analytics`                    | AdCP package projection                             |
| `by_catalog_item` | `durable entity mapping`                | Returned when the package has catalog-item identity |

## Conversion and audience support

* **Optimization:** Purchase/add-to-cart and lead/signup goals map to one exact conversion tag; optional CPA targets preserve micro-currency precision.
* **Event-source setup:** Returns a buyer-instrumented Pinterest Tag snippet and installation instructions. It makes no Pinterest API call and emits no built-in provider event source.
* **Event ingestion:** Activation is blocked: log\_event is absent from public tools/list. A provider-authoritative guarded implementation remains internal until trusted selected-account/source bindings and signed live evidence are available.
* **Audiences:** Audience synchronization and targeting are activation-blocked and are not claimed as publicly available while every governed lifecycle stage remains pending.

## Known limits

* Catalog Sales is blocked until the full catalog execution path is complete.
* Idea Pins are blocked until creative upload, materialization, and reverse readback are complete.
* Existing Pins remain hidden outside the governed canary path; that restriction is not evidence that a signed live run passed. Ordinary self-serve formats are standard image, video, and max-width video Pins.
* Placement-group selection is not exposed; executable products currently use ALL.
* Pinterest analytics can take up to 72 hours to stabilize, and supported attribution windows remain provider constrained.
* The protected harness is ready, but canonical run 29671483671 skipped every Pinterest check because no dedicated staging account was configured; complete lifecycle, creative round-trip, and delivery remain ready\_for\_live.
* sync\_catalogs is partial: it registers feed URLs only and does not push inline catalog items.
* get\_account\_financials is partial: campaign spend aggregation exists, while the v6 AccountStore variant returns UNSUPPORTED\_FEATURE pending context threading.
* Audience synchronization and include/exclude targeting are activation-blocked: every governed lifecycle stage remains pending and the audience canary is blocked.
* log\_event is absent from public tools/list. Its provider-authoritative guarded implementation remains internal until sync\_event\_sources publishes trusted selected-account/source bindings and a signed dedicated-account canary passes.

## Public review endpoints

* [AAO registry record](https://agenticadvertising.org/api/registry/publisher?domain=pinterest.com\&include=placements)
* Staging MCP/AdCP state: `relationship_gated_storefront_id_required`.
* Route template after a storefront relationship supplies its registered platform ID: `https://api.staging.interchange.io/seller/{registered_storefront_platform_id}/mcp`
* No provider-ID-derived URL is published. The shared MCP route requires the registered storefront platform ID assigned to the relationship; the adapter provider ID pinterest is not asserted to be that record ID.

The staging endpoint is connection-gated. Its presence here is not an invitation
to send mutating requests without a jointly approved test account and canary window.

## Provider references

* [Pinterest Ads API overview](https://developers.pinterest.com/docs/api/v5/)
* [Pinterest campaigns and ad groups](https://developers.pinterest.com/docs/work-with-ads/create-campaigns-and-ad-groups/)
* [Pinterest ads](https://developers.pinterest.com/docs/work-with-ads/create-ads/)
* [Pinterest targeting](https://developers.pinterest.com/docs/work-with-targets-and-audiences/set-up-targets-for-your-ads/)
* [Pinterest analytics](https://developers.pinterest.com/docs/work-with-analytics/overview/)

## Review questions

* Does campaign → ad group → ad → Pin describe the provider hierarchy and ownership boundary accurately?
* Are Standard, Video, and Max-width Video Pins the right ordinary self-serve creative scope, with existing Pins limited to governed canary proof?
* Is placement\_group ALL the correct current boundary when no per-placement AdCP selector is exposed?
* Are the conversion-tag, audience, catalog, and reporting mappings accurate, including the analytics stabilization caveat?
* Which market, account-permission, or product-eligibility distinctions should be added without implying that every account is eligible?