Amazon Ads Events API: sending conversions to Amazon Ads server-side

What the Events API does

The Events API is the current interface for sending conversion events from your own channels to Amazon Ads. Amazon calls it the successor of Conversions API v1 and points new integrations to the Events API. The transfer runs server-to-server: your backend, your CRM or a customer data platform talks to Amazon Ads directly, not the browser.

The reason is measurability: browser tracking is blocked by ad blockers, browser settings and cookie limits. The server path bypasses that and at the same time delivers more identifiers, for example email, phone number and rampID. The events sent are used for attribution and measurement of the associated campaigns and show up in the Amazon DSP reports, in Amazon Marketing Cloud and in Ads Data Manager.

Requirements

• Access through Login with Amazon (LWA) to the account you send for: an Amazon DSP advertiser account, a global account or a manager account.
• The header Amazon-Ads-ClientId (client ID from LWA), Amazon-Ads-AccountId (DSP advertiser ID or global account ID) or Amazon-Ads-Manager-AccountId for manager accounts.
• A call via POST /adsApi/v1/create/events with up to 500 events per request.
• A dataset name is optional but recommended. Without a name, new conversion definitions end up in the default_events dataset.

The Events API works for Amazon DSP, Sponsored Display and Sponsored TV. Amazon points out that the integration is primarily designed for Amazon DSP and that Sponsored Ads may need additional configuration or a different approach depending on the setup.

Conversion definitions: no manual step any more

With CAPI v1 you had to create a conversion definition before the first event and associate it with an order, otherwise the data flow stayed invisible in AMC. The Events API takes that step away from you: it creates conversion definitions automatically, and only from the fields of the eventDescription object.

Those fields also form the uniqueness criterion: events with the same name, the same conversionType, the same eventSource, the same eventIngestionMethod and the same dataSetName end up in the same conversion definition. A new dataset name therefore creates a new definition.

For the migration from CAPI v1 Amazon names two routes: keep your existing definitions and send without a dataset name, or create new definitions with a new dataset name. In the second case Amazon recommends keeping the old definitions in the account for at least 30 days so that attribution for running campaigns does not break, and creating new audiences with the updated definitions.

The required fields of an event

Other fields: unitsSold (only for OFF_AMAZON_PURCHASES, default 1), eventId for de-duplication, customData for your own attributes and dataProcessingOptions for LIMITED_DATA_USE. Amazon allows ten custom attributes plus brand, productId and category; according to Amazon named attributes can currently only be evaluated via AMC, so keep using attr1 to attr10 for DSP campaigns.

Match keys and hashing

Match keys are the identifiers through which Amazon attributes your event to a traffic event. The more identifiers you send, the better the match. Personal fields such as EMAIL, PHONE, FIRST_NAME, LAST_NAME, ADDRESS, CITY, STATE and POSTAL you normalise according to the Amazon formatting rules and then hash with SHA-256.

By contrast, MAID, RAMP_ID, MATCH_ID, REAL_ID, MERKLE_ID, KANTAR_ID and AREF_TOKEN are not hashed. You send FIP as a plaintext IP address. AREF_TOKEN is particularly interesting for the attribution section: you take the 10-character aref token from the landing page URL and the time of the page view as 13-digit UTC epoch milliseconds and send both as a token.timestamp pair. Amazon ignores a token if its timestamp is after the eventTime or more than 30 days before it.

Consent in the EU

For EU advertisers the consent information is mandatory. You pass exactly one signal: either the IAB Transparency & Consent Framework string (TCF), the Global Privacy Platform (GPP) or the Amazon Consent Signal (ACS). If you send multiple signals, Amazon uses TCF and ignores ACS.

The Amazon Consent Signal consists of three parameters: CountryCode in ISO 3166 format, amzn_user_data with GRANTED or DENIED for the processing of personal data and amzn_ad_storage with GRANTED, DENIED or NULL for reading and writing advertising cookies. If storage is not relevant, you may send NULL or leave the parameter out. The country code is mandatory: data uploaded without a country code is rejected.

For the German-speaking market that is the concrete consequence: without a valid signal the server-side import is not compliant in the EU. That assessment is ours, not Amazon’s; Amazon describes the requirement as a consent disclosure for EU advertisers.

De-duplication: Ad Tag and Events API in parallel

If you run the Amazon Ad Tag and the Events API in parallel, Amazon will otherwise report the same action twice. The trick is a shared identifier: you set clientDedupeId in the tag and send the same value as eventId in the API call. Amazon then counts only one conversion. De-duplication is not needed if client and server send disjoint event types.

Amazon de-duplicates in three ways. First by timestamp: if several events of the same user with the same conversion attributes arrive within a 200ms window, Amazon keeps only the first. Second by the de-duplication ID: with the same clientDedupeId or eventId the event with the earliest publication timestamp wins, and on a tie the order is Events API, Amazon Ad Tag, Mobile Measurement Partner. Third by the count method: if the count method is set to FIRST, only one conversion per user within 24 hours is counted.

The ID may be at most 256 characters long and must be unique per event: an ID you use for several events blocks the further events. Amazon rejects any later repeat of the same ID within 90 days. You can check the result in the Events Manager under Off Amazon attribution > Conversions in the Excluded events column: if nothing shows up there, the IDs do not match.

What ends up in AMC

Events sent through the Events API can be evaluated in AMC via the conversions table. The event_category column is always off-Amazon for such events, conversion_event_name carries the name of your conversion definition and conversion_event_source_name the source of the delivered data. For off-Amazon events tracked_item holds the ID of the conversion definition. The event_subtype field carries numeric values for off-Amazon events and readable ones like detailPageView, shoppingCart, order or searchConversion for on-Amazon events.

Conversions are ad-attributed if a traffic event was served to the user within the 28 days before the conversion event. Those 28 days are exactly why a server-side event only appears as attributed after that time.

SELECT
  conversion_event_name,
  COUNT(DISTINCT user_id) AS buyers
FROM
  conversions
WHERE
  event_category = 'off-Amazon'
  AND event_date_utc BETWEEN '2026-10-01' AND '2026-10-31'
GROUP BY
  conversion_event_name

If, on the other hand, you want to analyse your own conversion data entirely within AMC, use the AMC data upload (ADU). The difference: events sent through the Events API land in Amazon Ads and therefore in the reports of the campaigns; conversions uploaded via ADU are available only in AMC, where they can create audiences and be sent to the DSP.

How to check that your events arrive

• After sending, events can take up to two hours to become visible in your account. Amazon explicitly names this delay.
• Check in the Events Manager: the Conversions tab shows the events sent, the total event count and the last activity. In Ads Data Manager the events additionally appear as conversion datasets.
• Watch for the failure patterns from the Amazon documentation: the wrong region in the destination settings, missing permissions in the Amazon account, validation errors, unaccepted terms and conditions and a wrong advertiser ID. When migrating from CAPI v1 to the Events API the most frequent cause is a definition that was only created under CAPI v1 and no longer exists in the new dataset context.

Step by step

1. Clarify access and account ID. Check whether you have Login with Amazon access to a DSP advertiser account, a global account or a manager account. Note the client ID, the advertiser ID and the region of the account.
2. Decide the consent path. Choose exactly one signal: TCF, GPP or the Amazon Consent Signal with CountryCode, amzn_user_data and amzn_ad_storage. For EU accounts it is mandatory.
3. Plan dataset and definition. Give a meaningful dataset name, for example one per shop. The name is immutable and part of the uniqueness criterion for conversion definitions.
4. Normalise and hash match keys. Format email, phone number and address fields according to the Amazon rules and hash them with SHA-256. Send device and platform IDs without hashing.
5. Align de-duplication with the Ad Tag. Do not send the same action twice: clientDedupeId in the tag and eventId in the API call with an identical value.
6. Check the result. Wait up to two hours and check the Conversions tab and the Excluded events column in the Events Manager. Then check the conversions table in AMC with event_category = off-Amazon.

Frequently asked questions