Guide
A complete guide to Amazon Marketing Stream
GUIDE
Amazon Ads Media Planning APIs help media teams forecast performance, uncover audience insights, and optimize budget allocation before media dollars are committed.
This guide follows a media strategist’s journey across the full campaign lifecycle from strategic planning and audience development to execution and measurement. Amazon’s Media Planning APIs support practitioners across planning, analyst, and buyer roles. Client details have been anonymized. Figures throughout are illustrative examples demonstrating API capabilities.
The $150M question
I’m a media strategist at a mid-size advertising agency. A wellness brand came to us with $150 million to spend on Amazon. They had one question: “Can you guarantee this will work?”
I couldn’t. None of us could. We had 15 years of experience, thousands of campaigns behind us, and genuine belief in the product. But we didn’t have certainty. We were building a $150 million media plan the same way architects designed buildings before structural engineering existed: experience, intuition, and hope. Inside, we were terrified. Three months in, the client asked: “Are we reaching our target audience like you predicted?” I had no idea. We couldn’t accurately measure unique reach across channels. Our reach projections? Educated guesses.
Six months later, I attended an Amazon Ads conference and learned about Media Planning APIs that would have answered every question we couldn’t answer:
Today, that same client invests $200 million annually not by spending more on the same channels, but by expanding into new personas and inventory identified through the API suite and they do it with complete confidence. Not because we’re smarter. Because we stopped guessing.
An agency that forecasts can defend its recommendations with data, and clients reward that.
Think of media planning the way a film studio plans a big movie release. Before spending a dollar on production, the studio asks: Who is our audience? What channels will they be on? How much should we spend in each market? What return should we expect? Media planning works the same way for advertisers—it’s the strategic work you do before buying ads, so your campaign has a real shot at success.
Without a plan, you’re guessing. With the right tools, specifically Amazon’s Media Planning API suite, you’re forecasting. That difference is worth tens of millions of dollars.
Amazon’s Media Planning APIs are organized into four groups, each addressing a core planning challenge:
How many people did we reach, will we reach, and what’s the real overlap?
What outcomes can we predict before committing budget?
Who should we target and why?
How do we measure true media impact across channels?
All APIs operate over Amazon Ads inventory and behavioral signals. Cross-publisher reach, deduplication, performance comparison, and audience characterization require third-party measurement partners.
Every campaign moves through four phases, and the Media Planning APIs plug into each one.
Before spending a dollar, you analyze past results, forecast reach and performance, and build your plan. Reach Curve APIs, Performance Forecasting, and Audience APIs give you the data to do all three.
With your plan in hand, you set up targeting, configure channels, and finalize budget allocations. Audience APIs define who you’re reaching, while Reach Curve APIs (Reach Forecasting, Forecast Deduplication) help you validate your channel mix before launch.
Once the campaign is running, you monitor performance, adjust budgets, and optimize targeting. Reach Curve APIs (Forecast Deduplication) show whether you’re reaching unique customers or paying for overlap.
After the campaign ends, you measure actual vs. forecast, extract learnings, and plan the next campaign. Reach Curve APIs (Historic Reach) show what actually happened, and feeds those signals into your measurement framework.
Each API group answers core questions you couldn’t reliably answer before. Together, they transform how you plan, spend, and prove results. Here’s what each one does in plain language.
The Reach Curve group contains three APIs that work together to give you a complete picture of reach past, future, and deduplicated.
Before planning the client’s next campaign, we needed to know what actually happened in their previous campaigns. The client said: “We think we reached about 8 million customers last quarter.” Were those 8 million unique people? Or 5 million people seeing ads twice? We were flying blind.
Historic Reach gives you historical reach curves for Amazon inventory, scoped to your advertiser context. You give it a date range and audience parameters; it returns modeled unique-reach figures based on Amazon panel and inventory data. No guesswork. No assumptions.
We ran Historic Reach on the client’s past campaigns six months of data. Result: 12 million unique customers not 8 million. A 50% measurement gap. That changed everything. Their cost per reach was 37% lower than they thought, making their campaigns far more efficient than their initial metrics suggested. They weren’t underperforming—they were under-measuring. With that baseline, we could confidently plan a $150M campaign.
Historic Reach looks backward, not forward. It won’t predict next quarter. But you can’t build a good forecast without understanding your actual starting point. Think of it as reading last year’s financials before setting next year’s budget essential context, not the full strategy. Not useful for first-time Amazon campaigns with no history.
The client asked: “Should we spend $120M, $150M, or $180M? What’s the difference in reach?” Traditionally, we’d guess rough linear scaling from last year’s spend? Those question marks... that’s where anxiety lives.
Reach Forecasting lets you test budget scenarios before spending anything. You put in your target audience, campaign dates, and multiple budget options. It returns a reach curve showing exactly how many unique customers each budget reaches and where the curve flattens (where extra spend stops delivering proportional reach).
Illustrative example demonstrating Reach Forecasting API capabilities:
| Budget | Unique Reach | Cost / Customer | Efficiency |
|---|---|---|---|
| $125M | 17.8M customers | $7.02 | Excellent |
| $150M | 20.4M customers | $7.35 | Recommended |
| $175M | 22.1M customers | $7.92 | Diminishing |
| $200M | 23.2M customers | $8.62 | Poor |
The curve flattened sharply after $150M. Going from $150M to $175M added only 1.7M customers at $14.70 per incremental customer versus a $7.35 average. We recommended saving that $25M and reallocating it to prospecting. The client’s reaction: “You just saved us $25 million before we spent it.”
These are projections, not guarantees similar to weather forecasts. Accuracy varies by campaign conditions; the ranges shown are illustrative examples based on typical performance patterns. Always present a confidence range e.g., “We predict 20.4M reach, with a likely range of 18.5M to 22.1M.” Plan with a margin, track actuals, and refine your models over time.
Halfway through the Q4 campaign, the client asked for a check-in. We told them we were reaching 21.6 million unique customers across multiple Amazon Ads channels. We felt good about that number. We were wrong.
Forecast Deduplication shows you how many unique people you’re actually reaching across all your Amazon channels not the inflated sum of each channel’s reach. It maps the overlap between channels so you can see exactly where you’re double-counting and paying for the same eyeballs twice.
Illustrative example demonstrating Forecast Deduplication API capabilities:
We ran Forecast Deduplication. Real unique reach: 13.2 million not 21.6 million. 8.4 million “customers” were the same people appearing across multiple channels. Connected TV channels had 68% overlap. We’d wasted reaching people we’d already reached. We restructured the media mix, cut overlapping channel budgets, shifted spend toward Twitch (where overlap was lower), and achieved 16.8M unique reach at the same $150M budget. A increase in unique reach for free.
“We were paying $61,000 to show the same people ads across five different screens. That’s not multi-channel strategy—that’s paying rent on the same apartment five times.”
Deduplication only works inside Amazon’s inventory. If you’re also running Google, Meta, TikTok, or linear TV, those overlaps won’t show up here. Tell clients upfront: “This shows Amazon audience overlap. For cross-publisher deduplication, you’ll need third-party measurement partners.” Set expectations clearly.
Reach is important. But the client’s real question was: “How efficiently will this campaign deliver?” They needed to know before committing $150 million what their cost-per-click would look like, what video completion rates they could expect, and whether the spend would deliver at scale. The best we could say was: “Based on industry averages trust us.”
Performance Forecasting predicts campaign outcomes before you spend a dollar. You select a metric (clicks, video completions, or detail page views) and the API returns a forecast curve: at each spend level, you get the predicted count, cost-per-outcome (CPC, eCPM, CPDPV, CPVC), and rate metrics (CTR, VCR). Not a hopeful estimate. A data-backed prediction with confidence intervals.
Illustrative example demonstrating Performance Forecasting API capabilities:
The API returned a forecast curve showing predicted clicks and cost-per-outcome at our planned spend level with confidence intervals that cleared the client’s efficiency benchmarks even at the low end. We walked into the planning meeting and said: “Even in the conservative scenario, your cost-per-outcome is within target. We recommend greenlighting this campaign.”
Three months later, actual click-through rates and cost-per-outcome landed within of the API’s forecast. The campaign ultimately delivered ROAS as a business outcome. That combination—accurate forecasts feeding confident decisions—changed the client relationship entirely and earned us a significant renewal.
Accuracy improves with data. Variance widens for new product launches and during peak periods. Campaigns with longer Amazon history produce tighter predictions. Communicate this clearly to clients: confidence intervals aren’t a hedge—they’re the honest truth about how predictions work.
The Audience API group helps you move beyond demographics to understand who your customers actually are and find new ones you didn’t know existed.
The client’s original target: “Adults 25–54, interested in health and wellness, household income $60K+.” That describes approximately 42 million people on Amazon. Which segments should we prioritize and how much should each get? Demographics tell you people are. They don’t tell you what people. And behavior predicts conversion far better than age brackets.
Together, they answer: “Who are our best customers, who else looks like them, and how do we avoid targeting the same people twice?”
Illustrative example demonstrating Audience API capabilities, with the remaining 10% reserved for testing new segments identified via Audience Discovery.
| Segment | Size | Behaviors | Relative Performance | Budget |
|---|---|---|---|---|
| Active Wellness Enthusiasts | 8.2M | Protein powder, fitness content, “post-workout” searches | 2.9x baseline | 50% |
| Health-Conscious Parents | 6.4M | Kids’ vitamins, natural remedies, family wellness | 1.7x baseline | 30% |
| Casual Health Browsers | 12.8M | Occasional vitamins, general entertainment | 0.6x baseline | 10% |
By shifting budget from broad demographics to behavioral personas, campaign efficiency improved significantly. The Active Wellness segment—just 8.2 million people—delivered the highest returns. They were the superfans all along. We just couldn’t see them until we looked at behaviors.
Audience Discovery then surfaced a segment we’d never considered: “Fitness content streamers who buy organic snacks.” Audience Overlap confirmed this group had less than 12% overlap with our existing targets a genuinely new audience, not a repackaged version of one we already had.
Audience APIs show behaviors through Amazon’s lens. If your customer primarily shops or consumes media outside of Amazon, the picture will be incomplete. Layer in your own first-party data for a fuller view. Also, not ideal for very small niche audiences where sample sizes limit meaningful clustering.
After the campaign ended, the client asked: “What was the real impact of our Amazon investment compared to our other channels?” We had platform-level metrics, but no standardized way to feed Amazon’s signals into their broader measurement models. Our analytics team spent days manually pulling reports, reformatting data, and reconciling discrepancies by the time insights reached the planning team, the next campaign was already in-flight.
MMM API gives advertisers and measurement partners programmatic access to Amazon’s advertising and retail signals for faster, more scalable Marketing Mix Modeling. It eliminates manual data exchanges and automates delivery of media signals (impressions, reach, spend) and retail signals including daily shopping engagement metrics like add-to-cart events directly into existing workflows. The result: more frequent, reliable insights for cross-channel budget optimization.
Illustrative example demonstrating MMM API capabilities:
What used to take our analytics team days of manual data wrangling became automated. Amazon’s media and retail signals including granular shopping behavior data flowed directly into the client’s MMM on a daily cadence, not quarterly. The result: a clearer picture of how Amazon investment drove outcomes relative to other channels, updated frequently enough to actually inform the next budget decision rather than arriving too late to matter.
MMM API provides the signals—it doesn’t build the model for you. You’ll need an existing MMM framework (in-house or via a measurement partner) to ingest and analyze the data. The value is in the automation and standardization: consistent, programmatic access that reduces manual effort and enables more frequent analysis.
Start with Historic Reach to understand your baseline. Use Reach Forecasting and Performance Forecasting to plan your next campaign with confidence. Run Forecast Deduplication to eliminate wasted spend. Apply Audience APIs to sharpen who you’re targeting. Use MMM API to measure true cross-channel impact and inform the next cycle. Together, they turn the full planning cycle from “what happened” to “what will happen” to “what did it actually deliver” into a data-driven process.
Illustrative comparison; outcomes vary by category, baseline, and execution. API adoption was one of several changes during this period; improved creative, category growth, and operational maturity contributed alongside.
| Metric | Without APIs (Year 1) | With APIs (Year 3) | Change |
|---|---|---|---|
| Annual Budget | $85M | $150M | +76% scale |
| Unique Reach | 8M (estimated) | 16.8M (measured) | +110% |
| Campaign Efficiency | Baseline | Significant Improvement | +29% |
| Forecast Accuracy | N/A (guessing) | Data-driven | Predictable |
| Planning Time | 28 hours | 9 hours | -68% |
| Client Confidence | “Will this work?” | “What’s the forecast?” | Transformed |
Client relationships changed most. Before the APIs, clients asked “Will this campaign hit our targets?” and we answered “We’re confident trust us.” After, clients asked “What’s the forecast and confidence interval?” and we answered with data. That shift from vendor to strategic partner can drive significant improvements in client retention and grow revenue per client.
Planning time dropped from 28 hours to per campaign. We stopped building one plan and hoping. We started building five scenarios, comparing reach curves, and letting the data recommend the optimal spend. Major holding companies such as IPG, OMG, GroupM, WPP, Dentsu, and Publicis are integrating these APIs into their proprietary planning tools. If you’re an independent agency, these tools are how you maintain competitive parity.
Plan precisely. Spend confidently. Measure everything.
You don’t need to adopt every API at once. Here’s how we did it and how you can too:
New integrators should expect wider variance bands during the first 30 days while the model warms up to their traffic profile.
Start with the Amazon Ads API onboarding guide and connect with your Amazon Ads account team. They’ll walk you through developer registration, intake requirements, and help scope which APIs to prioritize for your use case.
Explore the resources listed below to help you get started with the Media Planning API suite.
The Amazon Ads API Guide and Media Planning Guides provide technical specs, endpoints, and integration guides. API documentation also provides current locale availability and API status.
Gigi, Pacvue, Perpetua, Intentwise, and Skai offer pre-built integrations with no coding required, including dashboards.
The Partner Network helps you find certified Amazon Ads partners who can help with implementation.
The Media Planning Certification offers free training on media planning fundamentals and API use.
Your Amazon Ads rep provides case studies, onboarding assistance, and pilot program access.
Not a developer? That’s fine. Several Amazon Ads partner platforms (Pacvue, Perpetua, Skai, Gigi, and others) are progressively integrating Media Planning APIs. Zero development time required. Work with your account team to identify the right partner for your stack.
In the past, I sat across from a client and said: “I think this campaign will work. We’ve done our best work planning this. Trust us.” Inside, I was terrified. I had experience, benchmarks, and instincts. But I didn’t have certainty.
Today, I sit across from that same client now spending $200 million annually and say: “Here’s the forecast: We predict 22.3M unique reach. The curve flattens after $185M, so we recommend spending $185M efficiently and reallocating $15M to test new personas. Here’s how we’ll track actuals every week. Here’s when we’ll adjust.”
The difference between those two conversations? A suite of APIs that removed the guesswork. We stopped saying “we think” and started saying “the forecast shows.” We stopped hoping campaigns would work and started predicting they would. We stopped being media buyers and became media strategists. The transformation was real:
| Before | After |
|---|---|
| Guessing at reach | Forecasting reach with data |
| Hoping performance would hit targets | Predicting outcomes with confidence intervals |
| Counting the same customers twice | Knowing true unique reach after deduplication |
| Targeting age brackets | Targeting behavioral personas that convert |
| Vendor: “Trust us” | Strategic partner: “Here’s the forecast” |
“Your clients are spending millions on Amazon and asking questions you can’t answer with certainty. With these APIs, you can. Plan precisely. Spend confidently. Measure everything.”
The only question is: Will you adopt them before your competitors do?
Use this table to quickly match each API to your planning situation.
| API | Best For | Availability | Prerequisites |
|---|---|---|---|
| Historic Reach | Benchmarking; correcting past measurement gaps | US, CA, MX, UK, DE, FR, IT, ES, AT, JP, AU | Campaign history (min. 6 months recommended) |
| Reach Forecasting | Testing budget scenarios; finding the spend “sweet spot” | US, CA, MX, BR, UK, DE, FR, IT, ES, NL, SE, TR, IN, AE, SA, JP, AU | Supported marketplace; audience parameters |
| Forecast Deduplication | Eliminating wasted spend; finding true unique reach across channels | Same as Reach Forecasting; confirm with your Amazon Ads account team | Multi-channel media mix |
| Performance Forecasting | Predicting campaign outcomes; building client confidence pre-launch | US, CA, MX, BR, UK, DE, FR, IT, ES, NL, SE, TR, IN, AE, SA, JP, AU | Campaign history improves accuracy |
| Persona Builder | Moving beyond demographics; finding high-converting behavioral clusters | US, CA, MX, BR, DE, ES, FR, IT, NL, SE, TR, UK, KSA, UAE, AU, IN, JP | AMC instance for first-party data layering |
| Audience Discovery | Finding new audience segments you haven’t considered | Same as Persona Builder | Sufficient category data |
| Audience Overlap | Understanding segment intersection; avoiding over-investment | Same as Persona Builder | Multiple active segments |
| MMM API | Measuring true media impact; automating signal delivery for MMMs | US, CA, UK, FR, DE, IT, ES, JP, AU, MX, BR, KSA, IN | Existing MMM framework (in-house or partner) |
For current locale availability and API status, visit advertising.amazon.com/API/docs or contact your Amazon Ads account team.
Contributors:
Vic Awokoya, Kapil Dwivedi
Additional resources:
Amazon internal, US, 2025–2026.
Amazon Ads API documentation, WW, 2026.