> ## 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.

# Meta Ads adapter compatibility

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

Meta Ads maps AdCP media buys to campaigns, packages to ad sets, and creative assignments to ads across the governed Facebook and Instagram placement catalog.

<Note>
  **Review-ready, not provider-endorsed · last verified 2026-08-16.**
  This is an Interchange compatibility review for technical feedback, not a Meta certification or endorsement. “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 | `partial`                                 | Current code classifies 32 provider-observed creation-flow leaves. Partial means this is not a certified complete inventory of every Ads Manager 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, and billing tuple; Pages, identities, forms, event sources, catalogs, audiences, creative, targeting, budget, and flight are separate runtime bindings. |
| Current account eligibility   | `account_check_required`                  | Business permissions, ad-account eligibility, Page and identity ownership, resource readiness, market, and provider feature access 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/meta/adapter.ts, docs/adapter-plans/meta.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/meta/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 21 configured objective mappings are executable and classified by drift tests.                                                                                                            |
| Fresh signed live evidence      | `not_publicly_asserted` | —             | Protected canary families exist, but this public contract does not claim a current live pass without a dated signed artifact for the exact account, product, resources, and fixture revision. |
| AAO discovery                   | `community_catalog`     | 2026-08-16    | The public record exposes six governed Facebook and Instagram placements 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    | Meta Ads                       | Mapping                                                                                   |
| --------------------- | ------------------------------ | ----------------------------------------------------------------------------------------- |
| `account`             | `ad account`                   | Explicit selected ad account under the authorized Meta business.                          |
| `media_buy`           | `campaign`                     | Campaign objective and lifecycle.                                                         |
| `package`             | `ad set`                       | Optimization, billing event, budget, flight, targeting, placement, and conversion source. |
| `creative`            | `ad creative`                  | Image, video, existing-post, and governed creative shapes.                                |
| `creative_assignment` | `ad`                           | Ad binds one creative to one ad set.                                                      |
| `signal`              | `Custom or Lookalike Audience` | Account-owned audience identity and readiness.                                            |

## Operations

| Public adapter operation | Surface              | State             | Provider path                                                                                                                 |
| ------------------------ | -------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `list_accounts`          | AdCP buyer operation | `implemented`     | Business/ad-account discovery and explicit selection                                                                          |
| `sync_accounts`          | AdCP buyer operation | `not_implemented` | Account synchronization is not implemented.                                                                                   |
| `get_products`           | AdCP buyer operation | `implemented`     | 21 objective/optimization/billing mappings                                                                                    |
| `sync_creatives`         | AdCP buyer operation | `implemented`     | Ad image/video/creative creation with assignment readback                                                                     |
| `list_creatives`         | AdCP buyer operation | `implemented`     | Ad creative inventory and assignment projection                                                                               |
| `create_media_buy`       | AdCP buyer operation | `implemented`     | Campaign → ad set → ad                                                                                                        |
| `get_media_buys`         | AdCP buyer operation | `implemented`     | Campaign/ad-set/ad projection with targeting provenance                                                                       |
| `update_media_buy`       | AdCP buyer operation | `implemented`     | Lifecycle, geography, audiences, placements, devices, and creative assignments; AdCP 3.2 budget/bid replacement is not atomic |
| `get_media_buy_delivery` | AdCP buyer operation | `implemented`     | Insights API campaign/ad-set reporting plus placement, device, and geography breakdowns                                       |
| `get_signals`            | AdCP buyer operation | `implemented`     | Custom and Lookalike Audience discovery                                                                                       |
| `sync_audiences`         | AdCP buyer operation | `implemented`     | Custom Audience create/replace/status lifecycle                                                                               |
| `sync_event_sources`     | AdCP buyer operation | `implemented`     | Pixel, app, and supported built-in event source discovery                                                                     |
| `log_event`              | AdCP buyer operation | `implemented`     | Conversions API event ingestion                                                                                               |
| `sync_catalogs`          | AdCP buyer operation | `implemented`     | Catalog synchronization                                                                                                       |
| `get_account_financials` | AdCP buyer operation | `implemented`     | Account currency, funding, and spend constraints                                                                              |

## Wholesale products and exact execution bases

| Product ID                                 | Exact provider execution base                                                             | Implemented   | Static certification     | Current eligibility      | Known gap |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------- | ------------------------ | ------------------------ | --------- |
| `meta_awareness`                           | objective `OUTCOME_AWARENESS`; optimization `REACH`; billing `IMPRESSIONS`                | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_awareness_impressions`               | objective `OUTCOME_AWARENESS`; optimization `IMPRESSIONS`; billing `IMPRESSIONS`          | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_awareness_ad_recall`                 | objective `OUTCOME_AWARENESS`; optimization `BRAND_AWARENESS`; billing `IMPRESSIONS`      | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_traffic`                             | objective `OUTCOME_TRAFFIC`; optimization `LINK_CLICKS`; billing `LINK_CLICKS`            | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_traffic_landing_page_views`          | objective `OUTCOME_TRAFFIC`; optimization `LANDING_PAGE_VIEWS`; billing `IMPRESSIONS`     | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_engagement_page_likes`               | objective `OUTCOME_ENGAGEMENT`; optimization `PAGE_LIKES`; billing `PAGE_LIKES`           | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_engagement_instagram_profile_visits` | objective `OUTCOME_ENGAGEMENT`; optimization `PROFILE_VISIT`; billing `IMPRESSIONS`       | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_engagement_instagram_conversations`  | objective `OUTCOME_ENGAGEMENT`; optimization `CONVERSATIONS`; billing `IMPRESSIONS`       | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_engagement`                          | objective `OUTCOME_ENGAGEMENT`; optimization `POST_ENGAGEMENT`; billing `POST_ENGAGEMENT` | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_engagement_video_views`              | objective `OUTCOME_ENGAGEMENT`; optimization `THRUPLAY`; billing `THRUPLAY`               | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_engagement_messenger`                | objective `OUTCOME_ENGAGEMENT`; optimization `CONVERSATIONS`; billing `IMPRESSIONS`       | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_engagement_whatsapp`                 | objective `OUTCOME_ENGAGEMENT`; optimization `CONVERSATIONS`; billing `IMPRESSIONS`       | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_conversions`                         | objective `OUTCOME_SALES`; optimization `OFFSITE_CONVERSIONS`; billing `IMPRESSIONS`      | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_sales_website_value`                 | objective `OUTCOME_SALES`; optimization `VALUE`; billing `IMPRESSIONS`                    | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_app_installs`                        | objective `OUTCOME_APP_PROMOTION`; optimization `APP_INSTALLS`; billing `APP_INSTALLS`    | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_leads`                               | objective `OUTCOME_LEADS`; optimization `LEAD_GENERATION`; billing `IMPRESSIONS`          | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_leads_website`                       | objective `OUTCOME_LEADS`; optimization `OFFSITE_CONVERSIONS`; billing `IMPRESSIONS`      | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_leads_messenger`                     | objective `OUTCOME_LEADS`; optimization `LEAD_GENERATION`; billing `IMPRESSIONS`          | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_leads_instagram`                     | objective `OUTCOME_LEADS`; optimization `LEAD_GENERATION`; billing `IMPRESSIONS`          | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_leads_whatsapp`                      | objective `OUTCOME_LEADS`; optimization `LEAD_GENERATION`; billing `IMPRESSIONS`          | `implemented` | `deterministic_contract` | `account_check_required` | —         |
| `meta_leads_calls`                         | objective `OUTCOME_LEADS`; optimization `QUALITY_CALL`; billing `IMPRESSIONS`             | `implemented` | `deterministic_contract` | `account_check_required` | —         |

## 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                                    |
| ----------------------------- | ---------------- | ------------------------------- | ------------------------------------------------- |
| `meta_image_feed`             | `image`          | `executable`                    | object\_story\_spec.link\_data                    |
| `meta_video_feed`             | `video_hosted`   | `executable`                    | object\_story\_spec.video\_data                   |
| `meta_existing_post`          | `native_in_feed` | `canary_only`                   | authorized existing Page post                     |
| `meta_stories`                | `video_hosted`   | `executable`                    | vertical video creative + story placement         |
| `meta_reels`                  | `video_hosted`   | `executable`                    | vertical video creative + reels placement         |
| `meta_carousel`               | `image_carousel` | `declared_not_buyer_selectable` | object\_story\_spec.link\_data.child\_attachments |
| `meta_promoted_offerings`     | `image`          | `executable`                    | one ad set and creative per offering              |
| `meta_generated_image_1x1`    | `native_in_feed` | `declared_not_buyer_selectable` | generated square image                            |
| `meta_generated_stories_9x16` | `native_in_feed` | `declared_not_buyer_selectable` | generated vertical image                          |
| `meta_generated_video_feed`   | `video_hosted`   | `declared_not_buyer_selectable` | generated feed video                              |
| `meta_generated_reels_9x16`   | `video_hosted`   | `declared_not_buyer_selectable` | generated vertical video                          |
| `meta_generated_offerings`    | `native_in_feed` | `declared_not_buyer_selectable` | generated image per offering                      |

## Placements

| Placement ID        | Surface           | State         | Provider mapping           |
| ------------------- | ----------------- | ------------- | -------------------------- |
| `facebook_feed`     | Facebook Feed     | `implemented` | facebook / feed            |
| `facebook_stories`  | Facebook Stories  | `implemented` | facebook / story           |
| `facebook_reels`    | Facebook Reels    | `implemented` | facebook / facebook\_reels |
| `instagram_feed`    | Instagram Feed    | `implemented` | instagram / stream         |
| `instagram_stories` | Instagram Stories | `implemented` | instagram / story          |
| `instagram_reels`   | Instagram Reels   | `implemented` | instagram / reels          |

## Targeting

| AdCP dimension     | State              | Provider mapping                                                                                                   |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `geo_countries`    | `implemented`      | geo\_locations.countries                                                                                           |
| `geo_regions`      | `implemented`      | ISO subdivision → provider region key with provenance                                                              |
| `geo_places`       | `provider_limited` | Negotiated AdCP 3.2 stable provider city IDs; seller-wide advertisement awaits the authenticated resolver endpoint |
| `geo_postal_areas` | `implemented`      | geo\_locations.zips                                                                                                |
| `ext`              | `provider_limited` | Pre-3.2 ext.scope3.geo\_places city compatibility only                                                             |
| `age_ranges`       | `implemented`      | age\_min + age\_max                                                                                                |
| `user_age_unknown` | `implemented`      | Explicit unknown-age policy                                                                                        |
| `genders`          | `implemented`      | genders                                                                                                            |
| `device_type`      | `implemented`      | device\_platforms                                                                                                  |
| `audience_include` | `implemented`      | custom\_audiences                                                                                                  |
| `audience_exclude` | `implemented`      | excluded\_custom\_audiences                                                                                        |
| `frequency_cap`    | `implemented`      | Promoted-object and provider frequency controls where objective permits                                            |
| `placement_refs`   | `implemented`      | publisher\_platforms + position arrays for six public placements                                                   |

## Reporting

| AdCP output       | Provider source                                                      | Notes                                                            |
| ----------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `impressions`     | `impressions`                                                        | Campaign and ad-set totals                                       |
| `clicks`          | `clicks`                                                             | Campaign and ad-set totals                                       |
| `spend`           | `spend`                                                              | Account-currency amount                                          |
| `reach`           | `reach`                                                              | Unique accounts when returned                                    |
| `frequency`       | `frequency`                                                          | Provider frequency                                               |
| `conversions`     | `actions`                                                            | Mapped according to the committed optimization contract          |
| `completed_views` | `video_thruplay_watched_actions`                                     | ThrUPlay mapping                                                 |
| `breakdowns`      | `publisher_platform + platform_position \| device \| country/region` | Placement, device, and geography projections with reconciliation |

## Conversion and audience support

* **Optimization:** Website, app, lead, message, call, and value goals are represented by explicit product mappings.
* **Event sources:** Pixels, apps, and supported built-in sources are discovered and validated.
* **Event ingestion:** Conversions API events are supported through log\_event.
* **Audiences:** Custom Audience synchronization, readiness polling, inclusion, and exclusion are implemented.

## Known limits

* Messenger Inbox, Messenger Stories, and Threads Feed remain canary candidates rather than public placements.
* Existing-post creative sync remains restricted to the signed paused canary.
* AdCP 3.2 budget and bidding replacement is not exposed as an atomic update; create a replacement media buy instead.
* Provider account permissions, Page/Instagram/WhatsApp ownership, and objective eligibility can narrow the catalog.

## Public review endpoints

* [AAO registry record](https://agenticadvertising.org/api/registry/publisher?domain=facebook.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 meta 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

* [Meta Marketing API overview](https://developers.facebook.com/docs/marketing-apis/overview)
* [Meta Campaign reference](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group)
* [Meta Ad Set reference](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign)
* [Meta Insights API](https://developers.facebook.com/docs/marketing-api/insights)

## Review questions

If a provider mapping is incomplete or has changed, send the exact product, format, targeting dimension, metric, market, or provider API field that differs. We update the governed contract and add code-owned drift checks where a denominator exists; otherwise the explicit non-enforced provenance gap remains.