Loading docs...

👋 Need help? Chat with us!

Meta Marketing API v23.0: What's New

Everything Meta shipped in Marketing API v22-v25 and how AdsMAA exposes it — Advantage+ Suite, Advantage+ Creative (AI), Threads ads, Business AI, Incremental Attribution, and the legacy surfaces being killed off.

Intermediate12 min readUpdated 2026-05-17

Meta's Marketing API moves fast. Between Jan 2025 and Feb 2026 they shipped four major versions (v22 → v25) and killed off chunks of the legacy surface. This article covers what changed, what AdsMAA wraps for you, and what you need to migrate before the deadlines hit.

TL;DR — AdsMAA now targets v23.0 by default and exposes 30 new MCP tools covering Advantage+ Suite, Advantage+ Creative AI, Threads ads, Business AI, and modern measurement. If you have legacy ASC or AAC campaigns, you have until 2026-05-19 to migrate them.

Why this matters now

Meta is not just adding features — they're removing them too. The Marketing API enforces hard deadlines:

Date	What stops working
2025-09-09	All pre-v22.0 requests blocked (past)
2026-05-19	ASC + Advantage+ App campaign create/update blocked on every Marketing API version
2026-05-21	Graph API v19 deprecated
2026-09-24	Graph API v20 deprecated
~2026-09 (v26.0)	Remaining ASC/AAC campaigns auto-paused by Meta

If your code still calls these surfaces it will silently return empty data or hard-fail. The MCP tool

output

meta_api_version

returns this calendar live, so an AI agent can self-check before recommending features.

Version target + env override

Every Meta Graph call in AdsMAA — the backend services, all three MCP controllers (

output

/api/v1/mcp/live/*

output

/mcp/ext/*

output

/mcp/v23/*

), the pixel verification service, the Ads Library client — now reads:

output
process.env.META_API_VERSION || 'v23.0'

That means a single env var bump rolls everything forward. To test against v24 or v25 in staging, set

output

META_API_VERSION=v24.0

on the backend and MCP server containers, restart, and you're done. Tools like

output

meta_api_version

and

output

meta_deprecated_metrics

report the resolved version so agents know what they're calling.

Advantage+ Suite (unified objectives)

The legacy Advantage+ Shopping (ASC) and Advantage+ App (AAC) campaign types are being collapsed into unified objectives —

output

OUTCOME_SALES

output

OUTCOME_APP_PROMOTION

output

OUTCOME_LEADS

— with Advantage+ Audience as the default targeting strategy.

Old way	New way
ASC campaign with output `smart_promotion_type: AUTOMATED_SHOPPING_ADS`	output `live_meta_create_advantage_sales_campaign` (omit smart_promotion_type)
AAC campaign with output `smart_promotion_type: AUTOMATED_APP_ADS`	output `live_meta_create_advantage_app_campaign`
Lookalike + lookalike + lookalike stacks	output `live_meta_create_advantage_audience_adset`
Manual leads campaign	output `live_meta_create_advantage_leads_campaign`

Value Rules also landed in Marketing API:

output

live_meta_set_value_rules

lets you set bid multipliers from -90% to +1000% on age / gender / location / device / placement and (as of Apr 2026) custom audiences. Requires Value-Based Optimization to be enabled.

Meta reports +20-24% incremental conversions when ASC is replaced with the unified Advantage+ Sales flow, and -32% CPA in ecommerce benchmarks when lookalikes are replaced with Advantage+ Audience.

Advantage+ Creative (AI generation)

This is the largest new surface area. Meta now generates ad creative variants from a single source asset:

Tool	What it does
output `live_meta_advantage_creative_enable`	Turn on auto-enhancements on an ad set (brightness, uncrop, templates, text optimizations)
output `live_meta_advantage_creative_image_variants`	Generate N image variations from one source image hash
output `live_meta_advantage_creative_text_variants`	Generate headline / primary text / description variants, with optional brand-voice constraint
output `live_meta_advantage_creative_background_gen`	Generate new product backgrounds from a prompt
output `live_meta_advantage_creative_video_gen`	Animate a source image into a 15-20s video with optional text overlay + music (Beta — allowlist required)
output `live_meta_ai_dubbing`	AI-dub a video ad into target languages (Beta — allowlist required)
output `live_meta_creative_breakdown_insights`	Read back which AI variant performed best

The breakdown tool (Jul 2025) is the missing piece — without it, you'd never know which of the AI variants Meta picked actually drove the conversions.

Measurement — Incremental Attribution, EMQ, one-click CAPI

Tool	What changed
output `live_meta_set_incremental_attribution`	Apr 2025 — opt into Incremental Attribution mode. Optimizes for truly incremental conversions (cross-advertiser Conversion Lift), not last-click.
output `live_meta_get_event_match_quality`	Per-event EMQ 0-10 scores. <6 means weak signal optimization.
output `live_meta_enable_one_click_capi`	Apr 2026 — Meta-Enabled CAPI: zero-developer server-side setup. ~17.8% lower cost per result.
output `meta_deprecated_metrics`	Manifest of Insights metrics removed since Oct 2024 ( output `unique_actions` , output `cost_per_unique_action_type` , etc.). Check this before requesting insights.

Important: the Offline Conversions API was discontinued in May 2025. If you're still posting to

output

/offline_conversions

, those events are silently dropped. Use standard CAPI via

output

/events

. Also: MMM breakdowns are async-only now — sync queries return empty data without warning. AdsMAA's

output

live_meta_insights_breakdown

refuses

output

breakdowns=mmm

and points you at

output

live_meta_create_async_report

CTWA + WhatsApp Flows + Conversion Leads

Click-to-WhatsApp got first-class API support:

Tool	What it does
output `live_meta_create_ctwa_campaign`	Create the CTWA campaign skeleton
output `live_meta_create_ctwa_adset`	Wire destination=WHATSAPP, optimization=CONVERSATIONS, optional WhatsApp Flow ID
output `live_meta_create_whatsapp_flow`	Create a Flow — structured in-chat form/booking/qualification
output `live_meta_create_conditional_lead_form`	Lead form with conditional question branching + SMS/work-email verification
output `live_meta_set_conversion_leads_optimization`	Quality-Leads optimization (requires CRM CAPI feedback on qualified/disqualified status)

Meta reports -15% CPQL when Conditional Lead Forms + Conversion Leads + CRM CAPI are wired together.

Threads ads + Instagram publishing v2

Tool	New in
output `live_meta_threads_publish`	Threads API (Jul 2025) — text/image/poll/location/scheduled
output `live_meta_threads_advantage_catalog_ads`	Threads feed placements for Advantage+ Catalog Ads (Oct 2025)
output `live_meta_ig_set_alt_text`	Mar 2025
output `live_meta_ig_publish_with_paid_partnership`	Paid-partnership label in Content Publishing API
output `live_meta_ig_publish_trial_reel`	Reels visible only to non-followers (creative testing)

Business AI + AI Studio + Campaign Score

The agentic surface area:

Tool	What it does
output `live_meta_business_ai_configure`	Configure Business AI assistant for Messenger / WhatsApp / Instagram / 3P websites (Oct 2025)
output `live_meta_ai_studio_persona`	Create AI Studio personas with defined tone + purpose, usable as ad respondents
output `live_meta_get_campaign_score`	Read Meta's 0-100 grade of how well a campaign follows best-practice playbook, with per-recommendation confidence

Breaking changes already mitigated

AdsMAA sweeps these for you — no action required:

output
instagram_actor_id
→
output
instagram_user_id
(v23 rename). Backward-compat input accepted; auto-mapped to the new field.
output
live_meta_insights_breakdown
rejects
output
```
breakdowns=mmm
```
and points to the async pipeline.
output
live_meta_create_campaign
warns on legacy ASC/AAC
output
```
smart_promotion_type
```
and points to the unified tools.
output
meta_deprecated_metrics
manifest auto-discoverable so agents can avoid the silently-empty Insights fields.
Meta API deprecation headers (
output
```
x-fb-api-deprecation
```
) are logged on every backend response.

Beta-gated features (allowlist required)

These MCP tool wrappers exist and are correct, but the upstream surface is gated by Meta. Calls will return Meta errors until your ad account is on the allowlist:

output
```
live_meta_advantage_creative_video_gen
```
— Advantage+ Video Generation
output
```
live_meta_ai_dubbing
```
— multilingual ad dubbing
output
```
live_meta_business_ai_configure
```
— Business AI for Messenger/WA/3P
output
```
live_meta_ai_studio_persona
```
— custom AI personas

Reach out to your Meta representative or apply through the Meta for Business site to request allowlist access.

Next step: Migrate ASC/AAC campaigns before May 19, 2026

Key Takeaways

1AdsMAA targets Meta Marketing API v23.0 by default — bump via META_API_VERSION env var
230 new MCP tools added on top of the existing surface — 180 tools total
3Legacy Advantage+ Shopping (ASC) and Advantage+ App (AAC) are killed on 2026-05-19
4lookalike audiences are being retired in favor of Advantage+ Audience
5MMM breakdowns moved to async-only — sync queries silently drop data
6Several AI features (Video Gen, Dubbing, Business AI, AI Studio) require Meta allowlist

Frequently Asked Questions

I have a working ASC campaign. Will it stop running on May 19?

No — running campaigns keep running. What stops on May 19 is the ability to *create or update* ASC and AAC campaigns via the Marketing API. Already-live campaigns continue until ~Sep 2026 (v26.0), when Meta auto-pauses anything still using those legacy types.

Will my existing AdsMAA integration code keep working?

Yes. Existing tool names like live_meta_create_campaign are unchanged. New v23 tools are added alongside. Backward-compat is preserved across the board.

How do I know which Meta API version AdsMAA is targeting?

Call meta_api_version (or hit GET /api/v1/mcp/v23/api-version with an API key). It returns the resolved version, whether env override is set, and the full deprecation calendar.

Why are some new tools marked Beta?

Meta gates several new AI surfaces (Advantage+ Video Generation, AI Dubbing, Business AI, AI Studio personas) behind an allowlist while ramping. The MCP tool wrappers are ready; calls will return Meta errors until your ad account is allowlisted.

Where can I find the full list of new MCP tools?

Visit the /mcp page in your AdsMAA dashboard — new categories are labeled v23 — Advantage+ Campaigns, v23 — Advantage+ Creative, v23 — Measurement, v23 — Messaging & Lead Gen, v23 — Threads + IG Publishing, v23 — Catalog + Agentic.

Was this article helpful?

Ask a question

Continue Reading

integrations

ASC/AAC Migration: Beat the May 19, 2026 Deadline

How to find every Advantage+ Shopping and Advantage+ App campaign in your account before Meta blocks create/update, plus the exact replacement recipe.

integrations

Meta Ads Integration

Connect your Meta Business account to manage Facebook and Instagram campaigns with AI-powered optimization.

integrations

Meta Pixel + CAPI (Dual-Track)

Complete Meta tracking: server-side CAPI + automatic client-side Pixel for maximum attribution.

12 min

May 17, 2026

Intermediate

Key Takeaways

1AdsMAA targets Meta Marketing API v23.0 by default — bump via META_API_VERSION env var
230 new MCP tools added on top of the existing surface — 180 tools total
3Legacy Advantage+ Shopping (ASC) and Advantage+ App (AAC) are killed on 2026-05-19
4lookalike audiences are being retired in favor of Advantage+ Audience
5MMM breakdowns moved to async-only — sync queries silently drop data
6Several AI features (Video Gen, Dubbing, Business AI, AI Studio) require Meta allowlist

Topics

MetaMarketing APIv23Advantage+ThreadsCAPIchangelog

Loading docs...

Meta Marketing API v23.0: What's New

Intermediate12 min readUpdated 2026-05-17

Why this matters now

Meta is not just adding features — they're removing them too. The Marketing API enforces hard deadlines:

Date	What stops working
2025-09-09	All pre-v22.0 requests blocked (past)
2026-05-19	ASC + Advantage+ App campaign create/update blocked on every Marketing API version
2026-05-21	Graph API v19 deprecated
2026-09-24	Graph API v20 deprecated
~2026-09 (v26.0)	Remaining ASC/AAC campaigns auto-paused by Meta

If your code still calls these surfaces it will silently return empty data or hard-fail. The MCP tool

output

meta_api_version

returns this calendar live, so an AI agent can self-check before recommending features.

Version target + env override

Every Meta Graph call in AdsMAA — the backend services, all three MCP controllers (

output

/api/v1/mcp/live/*

output

/mcp/ext/*

output

/mcp/v23/*

), the pixel verification service, the Ads Library client — now reads:

output
process.env.META_API_VERSION || 'v23.0'

That means a single env var bump rolls everything forward. To test against v24 or v25 in staging, set

output

META_API_VERSION=v24.0

on the backend and MCP server containers, restart, and you're done. Tools like

output

meta_api_version

and

output

meta_deprecated_metrics

report the resolved version so agents know what they're calling.

Advantage+ Suite (unified objectives)

The legacy Advantage+ Shopping (ASC) and Advantage+ App (AAC) campaign types are being collapsed into unified objectives —

output

OUTCOME_SALES

output

OUTCOME_APP_PROMOTION

output

OUTCOME_LEADS

— with Advantage+ Audience as the default targeting strategy.

Old way	New way
ASC campaign with output `smart_promotion_type: AUTOMATED_SHOPPING_ADS`	output `live_meta_create_advantage_sales_campaign` (omit smart_promotion_type)
AAC campaign with output `smart_promotion_type: AUTOMATED_APP_ADS`	output `live_meta_create_advantage_app_campaign`
Lookalike + lookalike + lookalike stacks	output `live_meta_create_advantage_audience_adset`
Manual leads campaign	output `live_meta_create_advantage_leads_campaign`

Value Rules also landed in Marketing API:

output

live_meta_set_value_rules

lets you set bid multipliers from -90% to +1000% on age / gender / location / device / placement and (as of Apr 2026) custom audiences. Requires Value-Based Optimization to be enabled.

Meta reports +20-24% incremental conversions when ASC is replaced with the unified Advantage+ Sales flow, and -32% CPA in ecommerce benchmarks when lookalikes are replaced with Advantage+ Audience.

Advantage+ Creative (AI generation)

This is the largest new surface area. Meta now generates ad creative variants from a single source asset:

Tool	What it does
output `live_meta_advantage_creative_enable`	Turn on auto-enhancements on an ad set (brightness, uncrop, templates, text optimizations)
output `live_meta_advantage_creative_image_variants`	Generate N image variations from one source image hash
output `live_meta_advantage_creative_text_variants`	Generate headline / primary text / description variants, with optional brand-voice constraint
output `live_meta_advantage_creative_background_gen`	Generate new product backgrounds from a prompt
output `live_meta_advantage_creative_video_gen`	Animate a source image into a 15-20s video with optional text overlay + music (Beta — allowlist required)
output `live_meta_ai_dubbing`	AI-dub a video ad into target languages (Beta — allowlist required)
output `live_meta_creative_breakdown_insights`	Read back which AI variant performed best

The breakdown tool (Jul 2025) is the missing piece — without it, you'd never know which of the AI variants Meta picked actually drove the conversions.

Measurement — Incremental Attribution, EMQ, one-click CAPI

Tool	What changed
output `live_meta_set_incremental_attribution`	Apr 2025 — opt into Incremental Attribution mode. Optimizes for truly incremental conversions (cross-advertiser Conversion Lift), not last-click.
output `live_meta_get_event_match_quality`	Per-event EMQ 0-10 scores. <6 means weak signal optimization.
output `live_meta_enable_one_click_capi`	Apr 2026 — Meta-Enabled CAPI: zero-developer server-side setup. ~17.8% lower cost per result.
output `meta_deprecated_metrics`	Manifest of Insights metrics removed since Oct 2024 ( output `unique_actions` , output `cost_per_unique_action_type` , etc.). Check this before requesting insights.

Important: the Offline Conversions API was discontinued in May 2025. If you're still posting to

output

/offline_conversions

, those events are silently dropped. Use standard CAPI via

output

/events

. Also: MMM breakdowns are async-only now — sync queries return empty data without warning. AdsMAA's

output

live_meta_insights_breakdown

refuses

output

breakdowns=mmm

and points you at

output

live_meta_create_async_report

CTWA + WhatsApp Flows + Conversion Leads

Click-to-WhatsApp got first-class API support:

Tool	What it does
output `live_meta_create_ctwa_campaign`	Create the CTWA campaign skeleton
output `live_meta_create_ctwa_adset`	Wire destination=WHATSAPP, optimization=CONVERSATIONS, optional WhatsApp Flow ID
output `live_meta_create_whatsapp_flow`	Create a Flow — structured in-chat form/booking/qualification
output `live_meta_create_conditional_lead_form`	Lead form with conditional question branching + SMS/work-email verification
output `live_meta_set_conversion_leads_optimization`	Quality-Leads optimization (requires CRM CAPI feedback on qualified/disqualified status)

Meta reports -15% CPQL when Conditional Lead Forms + Conversion Leads + CRM CAPI are wired together.

Threads ads + Instagram publishing v2

Tool	New in
output `live_meta_threads_publish`	Threads API (Jul 2025) — text/image/poll/location/scheduled
output `live_meta_threads_advantage_catalog_ads`	Threads feed placements for Advantage+ Catalog Ads (Oct 2025)
output `live_meta_ig_set_alt_text`	Mar 2025
output `live_meta_ig_publish_with_paid_partnership`	Paid-partnership label in Content Publishing API
output `live_meta_ig_publish_trial_reel`	Reels visible only to non-followers (creative testing)

Business AI + AI Studio + Campaign Score

The agentic surface area:

Tool	What it does
output `live_meta_business_ai_configure`	Configure Business AI assistant for Messenger / WhatsApp / Instagram / 3P websites (Oct 2025)
output `live_meta_ai_studio_persona`	Create AI Studio personas with defined tone + purpose, usable as ad respondents
output `live_meta_get_campaign_score`	Read Meta's 0-100 grade of how well a campaign follows best-practice playbook, with per-recommendation confidence

Breaking changes already mitigated

AdsMAA sweeps these for you — no action required:

output
instagram_actor_id
→
output
instagram_user_id
(v23 rename). Backward-compat input accepted; auto-mapped to the new field.
output
live_meta_insights_breakdown
rejects
output
```
breakdowns=mmm
```
and points to the async pipeline.
output
live_meta_create_campaign
warns on legacy ASC/AAC
output
```
smart_promotion_type
```
and points to the unified tools.
output
meta_deprecated_metrics
manifest auto-discoverable so agents can avoid the silently-empty Insights fields.
Meta API deprecation headers (
output
```
x-fb-api-deprecation
```
) are logged on every backend response.

Beta-gated features (allowlist required)

These MCP tool wrappers exist and are correct, but the upstream surface is gated by Meta. Calls will return Meta errors until your ad account is on the allowlist:

output
```
live_meta_advantage_creative_video_gen
```
— Advantage+ Video Generation
output
```
live_meta_ai_dubbing
```
— multilingual ad dubbing
output
```
live_meta_business_ai_configure
```
— Business AI for Messenger/WA/3P
output
```
live_meta_ai_studio_persona
```
— custom AI personas

Reach out to your Meta representative or apply through the Meta for Business site to request allowlist access.

Next step: Migrate ASC/AAC campaigns before May 19, 2026

Key Takeaways

1AdsMAA targets Meta Marketing API v23.0 by default — bump via META_API_VERSION env var
230 new MCP tools added on top of the existing surface — 180 tools total
3Legacy Advantage+ Shopping (ASC) and Advantage+ App (AAC) are killed on 2026-05-19
4lookalike audiences are being retired in favor of Advantage+ Audience
5MMM breakdowns moved to async-only — sync queries silently drop data
6Several AI features (Video Gen, Dubbing, Business AI, AI Studio) require Meta allowlist

Frequently Asked Questions

I have a working ASC campaign. Will it stop running on May 19?

Will my existing AdsMAA integration code keep working?

Yes. Existing tool names like live_meta_create_campaign are unchanged. New v23 tools are added alongside. Backward-compat is preserved across the board.

How do I know which Meta API version AdsMAA is targeting?

Call meta_api_version (or hit GET /api/v1/mcp/v23/api-version with an API key). It returns the resolved version, whether env override is set, and the full deprecation calendar.

Why are some new tools marked Beta?

Where can I find the full list of new MCP tools?

Was this article helpful?

Ask a question

Continue Reading

integrations

May 17, 2026

Intermediate

Key Takeaways

1AdsMAA targets Meta Marketing API v23.0 by default — bump via META_API_VERSION env var
230 new MCP tools added on top of the existing surface — 180 tools total
3Legacy Advantage+ Shopping (ASC) and Advantage+ App (AAC) are killed on 2026-05-19
4lookalike audiences are being retired in favor of Advantage+ Audience
5MMM breakdowns moved to async-only — sync queries silently drop data
6Several AI features (Video Gen, Dubbing, Business AI, AI Studio) require Meta allowlist

Topics

MetaMarketing APIv23Advantage+ThreadsCAPIchangelog