Amazon Marketing Stream Integration Guide (2026)

Short answer

Amazon Marketing Stream pushes Amazon Ads performance data into an AWS account you own, so you stop polling the reporting API for intraday numbers. There are two versions running in parallel. Stream v1 sends hourly delta messages as JSON to an SQS queue or a Firehose stream, and Amazon shuts it off on 30 June 2027. Stream v2 writes Apache Parquet files to your S3 bucket, notifies an SQS queue for each delivery, carries total values rather than deltas, and can deliver as often as every 15 minutes. New integrations should start on v2; existing v1 consumers have until mid-2027 to move.

The facts below come from Amazon's Amazon Marketing Stream documentation, checked on 30 October 2026. Stream v2 is new and its pages change often; re-read them before you build.

When Stream is the right source

The Amazon Ads reporting API is built for daily and summary reports, and Amazon says so plainly: if you need data more often, use Stream, or expect throttling. The new reporting API is also capped for ad hoc use, at one concurrent report per advertiser and about 100 reports a day, according to Amazon's own Stream v2 overview. Our Amazon Ads API integration guide covers that side.

Stream earns its setup cost when you need any of these:

• hour-by-hour performance for dayparting, budget pacing or anomaly alerts;
• many advertiser accounts refreshed through the day without fighting report queues;
• a warehouse table that stays current with Amazon instead of a nightly snapshot;
• dimensions in one dataset that the reporting API splits across report types, such as a keyword's performance on a given placement.

If a daily refresh is enough, the reporting API is simpler and you can skip everything below.

Stream v1 and v2 compared

Amazon's Stream v2 overview lists the differences. In short:

The change from deltas to totals is the one that rewrites consumer code. A v1 pipeline adds each message to what it already holds, which means a lost message or a missing baseline corrupts every later number. A v2 pipeline overwrites a record with a newer version of the same record, which is easier to get right and easier to repair.

The v2 datasets

On 30 October 2026 the v2 dataset list holds two reporting datasets, each covering Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored TV and Amazon DSP in one schema:

• ads-performance-v1, hourly: traffic, spend and fees, engagement and attributed conversions. It replaces the four v1 performance datasets and folds in what reporting v3 split across campaign, ad group, ad, advertised product, search term, targeting, placement, inventory, geography and technology reports. Its dataset page gives a restatement window of 70 days.
• ads-converted-product-v1, daily.

Three properties of these datasets shape the warehouse. First, a new subscription delivers the advertiser's history for the restatement window within about a day, so there is no separate backfill job. Second, values for low-volume dimension values are grouped into a row labelled (Other) to protect privacy, while totals stay complete. Third, the dataset carries base metrics only; ROAS, CTR and similar ratios are yours to compute after aggregation.

v1 also had messaging datasets, with entity changes and budget consumption alerts whenever a budget allotment moved by 5% or more. The v2 list does not show a counterpart yet, so if your pacing logic depends on those messages, keep that part of v1 running and watch Amazon's release notes.

Setting up the destination

A v2 destination is an S3 bucket and a standard SQS queue in the same AWS region, as described in Set up your destination. The allowed regions depend on where you call the API:

• North America, API host advertising-api.amazon.com: destination in us-east-1
• Europe, API host advertising-api-eu.amazon.com: eu-west-1, eu-west-2 or eu-south-2
• Far East, API host advertising-api-fe.amazon.com: us-west-2 or ap-southeast-1

A v2 subscription delivers the advertiser's global data wherever the destination sits; the region only says where the bucket and queue live. Practical rules from Amazon's guide and our own projects:

• Use Amazon's CloudFormation template. It creates the bucket, the queue, a dead-letter queue, KMS keys, access logging and every policy Stream needs, and it removes the most common onboarding mistakes.
• Dedicate the bucket to Stream. Stream controls the key paths, and your own objects in the same bucket can collide with delivered files.
• Use one destination per client application. The first application to register a bucket and queue owns them.
• Test write permissions yourself. Stream checks only that the destination exists. A bucket policy without s3:PutObject leaves the subscription active while no data ever arrives, and nothing reports an error.

Creating a subscription

v2 subscriptions are created with POST /adsApi/v1/create/streamSubscriptions. Unlike most Ads API calls, the advertiser goes in the request body under accessRequestedAccounts, not in a scope header, alongside the dataset ID, the bucket ARN and the queue ARN. One request creates one subscription, pairing one dataset, one advertiser account and one destination.

Three details from the subscription guide catch people out:

• The account must be a Global Account ID (amzn1.ads-account.g. followed by an identifier) or a numeric Amazon DSP advertiser ID. A manager account ID, a Seller Central merchant ID or a Vendor group ID is rejected.
• The endpoint answers with a multi-status 207. Read the result from the success and errors arrays, not from the HTTP status.
• An account your client is not authorized for is refused at the gateway with a 401 whose message mentions "Bulk account authorization denied", even for a single account.

For agencies, that means an account registry keyed by Global Account ID, separate from the profile IDs the rest of the Ads API uses.

Consuming deliveries correctly

Each delivery writes one or more Parquet files and sends an SQS notification listing their S3 URIs, the dataset, and a streamBatch with a start time, an end time and a version. Amazon's data delivery page sets out the guarantees, and each one has a consequence for your consumer:

• At-least-once delivery. The same records can arrive twice under different S3 keys, so deduplicating by file name or delivery ID is wrong. Upsert each record on its full dimension key and keep the row with the highest streamBatch.version.
• No ordering. Notifications arrive out of order. Arrival time tells you nothing; the version does.
• Shared files. One Parquet file can hold rows for several subscriptions. Filter on the advertiser account rather than assuming one file per client.
• Split batches. One time window can arrive across several notifications. Process each as it comes; the version rule makes the result independent of grouping.

Two smaller traps. Batch windows are half-open, start inclusive and end exclusive, so consecutive batches never double-count a boundary row. And streamBatch.version can exceed the integer range of a double; read it as a 64-bit integer or a string, never as a JavaScript number or a float column, or version comparison silently breaks.

Read files from the notification rather than by listing the bucket. Listing is slower, costs more and invites processing a file twice.

Restatement and the staging layer

Attributed conversions mature for days after the click, so Amazon restates records: a corrected record arrives later as a newer version of the same key. With a 70-day window on ads-performance-v1, an hour from early September can still change in October.

The pattern Amazon recommends, and the one we build, has two layers. A staging table holds the latest version of every hourly record, updated by upsert. Reporting tables at daily, campaign or account level are rebuilt from staging for the affected windows, never incremented directly. Treat a record as final only after its restatement window has passed, and say so in the dashboard, so nobody compares last Tuesday's provisional sales with a finance export.

If you register the Parquet files in AWS Glue and query them with Athena, the currency and decimal fields land as decimal(18,8) and the counters as bigint. Plan for new fields to appear in the current dataset version, and for breaking changes to arrive as a new dataset version such as a future -v2.

Moving off Stream v1

Amazon's migration guide asks you to run both versions side by side and to validate before switching. The sequence:

1. Create the v2 destination.
2. Subscribe each advertiser to ads-performance-v1 and filter on adProduct.value where v1 had one subscription per ad product.
3. Rewrite the consumer from delta arithmetic to versioned upserts.
4. Reconcile v2 totals against v1 for the same windows.
5. Archive the v1 performance subscriptions only after the numbers agree.

Teams that stay on v1 until 2027 should know its constraints: standard SQS queues only, no FIFO; a separate IAM policy for each dataset and region; subscriptions through POST /streams/subscriptions with a clientRequestToken for idempotency; and an SQS subscription that sits in pending confirmation until it is confirmed. Amazon also warns that some v1 features may be limited before the shutdown date, which is a reason not to leave the migration to the last quarter.

What hourly data is good for

The common uses are dayparting, where bids follow the hours that convert; pacing, where budgets are not exhausted by mid-afternoon; and alerts on spend spikes or a campaign that stops serving. Each depends on hourly rows being complete, which is why the restatement handling above matters more than the transport.

Not every team needs to run AWS for this. If the goal is the hourly numbers in an AI client rather than your own pipeline, DataDoe, the data product our team engineers, reads Marketing Stream datasets intraday with under two hours of latency; they are off by default and switched on per account. Its post on Amazon PPC dayparting shows that workflow. A custom Stream integration stays the right choice when the data feeds your own bidding engine, product or warehouse.

How we scope a Stream project

We ask four questions first: which accounts and regions, how fresh the data must be, whether v1 is already running, and where the data has to end up. From there we set up destinations with Amazon's template, build the versioned staging layer, and run v1 and v2 in parallel with a reconciliation report until the numbers match.

Deltologic has built marketplace data integrations since 2020; see marketplace integrations for the scope and API migrations for moves like this one. Our guide to building an Amazon data connector covers the warehouse side. If you run Stream v1 today or need hourly ads data in your own stack, tell us what you have, and a senior engineer will reply with a migration plan.

Frequently asked questions

What is Amazon Marketing Stream?

Amazon Marketing Stream is an Amazon Ads service that pushes advertising performance data into an AWS account you own, hourly or more often, so you do not have to poll the reporting API for intraday numbers.

When is Amazon Marketing Stream v1 shut off?

Amazon shuts off Stream v1 on 30 June 2027. Existing v1 subscriptions keep delivering until then, though Amazon warns some v1 functionality may be limited earlier, so it recommends running v2 in parallel and migrating before that date.

How does Stream v2 deliver data?

Stream v2 writes Apache Parquet files to an S3 bucket you own and sends an SQS notification listing the files for each delivery. Each record carries the total value for its time window, and restated records are delivered again with a higher streamBatch.version.

How do I deduplicate Amazon Marketing Stream data?

In Stream v2, upsert each record on its full set of dimension fields and keep the row with the highest streamBatch.version. Delivery is at least once and unordered, so file names and delivery IDs cannot be used to deduplicate. Stream v1 consumers deduplicate on idempotency_id.