Amazon Ads Events API: Conversions serverseitig an Amazon Ads senden

Was die Events API macht

Die Events API ist die aktuelle Schnittstelle, um Conversion-Events aus eigenen Kanälen an Amazon Ads zu senden. Amazon nennt sie ausdrücklich den Nachfolger der Conversions API v1 und verweist für Neuanbindungen auf die Events API. Die Übertragung läuft Server-zu-Server: Ihr Backend, Ihr CRM oder eine Customer-Data-Plattform spricht direkt mit Amazon Ads, nicht der Browser.

Der Grund ist die Messbarkeit: Browser-Tracking wird von Adblockern, Browser-Einstellungen und Cookie-Grenzen blockiert. Der Server-Pfad umgeht das und liefert zugleich mehr Identifikatoren, etwa E-Mail, Telefonnummer und rampID. Die gesendeten Events dienen der Attribution und Messung der zugeordneten Kampagnen und erscheinen in den Amazon-DSP-Berichten, in Amazon Marketing Cloud und im Ads Data Manager.

Voraussetzungen

• Ein Zugang über Login with Amazon (LWA) auf das Konto, für das Sie senden: ein Amazon-DSP-Advertiser-Konto, ein globales Konto oder ein Manager-Konto.
• Der Header Amazon-Ads-ClientId (Client-ID aus LWA), Amazon-Ads-AccountId (DSP-Advertiser-ID oder globale Konto-ID) beziehungsweise Amazon-Ads-Manager-AccountId für Manager-Konten.
• Ein Aufruf per POST /adsApi/v1/create/events mit bis zu 500 Events je Anfrage.
• Ein Dataset-Name ist optional, aber empfohlen. Ohne Namen landen neue Conversion-Definitionen im Dataset default_events.

Die Events API funktioniert für Amazon DSP, Sponsored Display und Sponsored TV. Amazon weist darauf hin, dass die Integration primär für Amazon DSP ausgelegt ist und Sponsored Ads je nach Setup zusätzliche Konfiguration oder einen anderen Ansatz braucht.

Conversion-Definitionen: kein manueller Schritt mehr

Bei CAPI v1 mussten Sie vor dem ersten Event eine Conversion-Definition anlegen und sie einer Bestellung zuordnen, sonst blieb der Datenfluss in AMC unsichtbar. Die Events API nimmt Ihnen diesen Schritt ab: Sie legt Conversion-Definitionen automatisch an, und zwar allein aus den Feldern des eventDescription-Objekts.

Diese Felder bilden zugleich das Eindeutigkeitskriterium: Events mit gleichem name, gleichem conversionType, gleichem eventSource, gleichem eventIngestionMethod und gleichem dataSetName landen in derselben Conversion-Definition. Ein neuer Dataset-Name erzeugt deshalb eine neue Definition.

Für die Umstellung von CAPI v1 nennt Amazon zwei Wege: Sie behalten Ihre bisherigen Definitionen und senden ohne Dataset-Namen, oder Sie legen mit einem neuen Dataset-Namen neue Definitionen an. Im zweiten Fall empfiehlt Amazon, die alten Definitionen noch mindestens 30 Tage im Konto zu behalten, damit die Attribution für bereits laufende Kampagnen nicht abreißt, und neue Zielgruppen mit den aktualisierten Definitionen zu erstellen.

Die Pflichtfelder eines Events

Weitere Felder: unitsSold (nur für OFF_AMAZON_PURCHASES, Standard 1), eventId für die Deduplizierung, customData für eigene Attribute und dataProcessingOptions für LIMITED_DATA_USE. Amazon erlaubt zehn eigene Attribute plus brand, productId und category; benannte Attribute sind laut Amazon derzeit nur über AMC auswertbar, für DSP-Kampagnen weiterhin attr1 bis attr10 verwenden.

Match-Keys und Hashing

Match-Keys sind die Identifikatoren, über die Amazon Ihr Event einem Traffic-Event zurechnet. Je mehr Identifier Sie mitsenden, desto besser die Zuordnung. Personenbezogene Felder wie EMAIL, PHONE, FIRST_NAME, LAST_NAME, ADDRESS, CITY, STATE und POSTAL normalisieren Sie nach den Amazon-Formatregeln und hashen sie anschließend mit SHA-256.

Nicht gehasht werden dagegen MAID, RAMP_ID, MATCH_ID, REAL_ID, MERKLE_ID, KANTAR_ID und AREF_TOKEN. FIP senden Sie als Klartext-IP-Adresse. AREF_TOKEN ist besonders interessant für den Attribution-Abschnitt: Sie übernehmen den 10-stelligen aref-Token aus der Landingpage-URL und den Zeitpunkt des Seitenaufrufs als 13-stellige UTC-Epoch-Millisekunden und senden beides als token.timestamp-Paar. Amazon wertet ein Token nicht mehr, wenn sein Zeitstempel nach dem eventTime liegt oder mehr als 30 Tage davor.

Consent in der EU

Für Werbetreibende in der EU ist die Consent-Angabe Pflicht. Sie übergeben genau ein Signal: entweder den IAB-Transparency-&-Consent-Framework-String (TCF), das Global Privacy Protocol (GPP) oder das Amazon Consent Signal (ACS). Schicken Sie mehrere Signale, verwendet Amazon TCF und ignoriert ACS.

Das Amazon Consent Signal besteht aus drei Parametern: CountryCode im Format ISO 3166, amzn_user_data mit GRANTED oder DENIED für die Verarbeitung personenbezogener Daten und amzn_ad_storage mit GRANTED, DENIED oder NULL für das Lesen und Schreiben von Werbe-Cookies. Ist die Speicherung nicht relevant, dürfen Sie NULL senden oder den Parameter weglassen. Der Country-Code ist zwingend: Daten ohne Country-Code werden abgewiesen.

Für den deutschsprachigen Markt ist das die konkrete Rechtsfolge: Ohne gültiges Signal ist der serverseitige Import in der EU nicht regelkonform. Die Einordnung ist unsere, nicht die von Amazon; Amazon beschreibt die Pflicht als Consent-Angabe für Werbetreibende in der EU.

Deduplizierung: Ad Tag und Events API parallel

Fahren Sie den Amazon Ad Tag und die Events API parallel, meldet Amazon sonst dieselbe Aktion zweimal. Der Trick ist ein gemeinsamer Identifier: Sie setzen clientDedupeId im Tag und senden denselben Wert als eventId im API-Aufruf. Amazon zählt dann nur eine Conversion. Die Deduplizierung ist nicht nötig, wenn Client und Server disjunkte Eventtypen senden.

Amazon dedupliziert auf drei Wegen. Erstens über Zeitstempel: Kommen mehrere Events desselben Users mit denselben Conversion-Attributen innerhalb eines 200ms-Fensters an, behält Amazon nur das erste. Zweitens über die Deduplizierungs-ID: Bei gleicher clientDedupeId beziehungsweise eventId gewinnt das Event mit dem frühesten Veröffentlichungszeitstempel, bei Gleichstand die Reihenfolge Events API, Amazon Ad Tag, Mobile Measurement Partner. Drittens über die Zählmethode: Steht die Count-Methode auf FIRST, zählt nur eine Conversion pro User in 24 Stunden.

Die ID darf höchstens 256 Zeichen lang sein und muss pro Event eindeutig sein: Eine ID, die Sie für mehrere Events verwenden, blockiert die weiteren Events. Amazon lehnt jede spätere Wiederholung derselben ID innerhalb von 90 Tagen ab. Prüfen können Sie das Ergebnis im Events Manager unter Off Amazon attribution > Conversions in der Spalte Excluded events: Taucht dort nichts auf, passen die IDs nicht zusammen.

Was in AMC ankommt

Events, die über die Events API gesendet wurden, sind in AMC über die Tabelle conversions auswertbar. Die Spalte event_category ist für solche Events immer off-Amazon, conversion_event_name trägt den Namen Ihrer Conversion-Definition und conversion_event_source_name die Quelle der gelieferten Daten. In tracked_item steht bei Off-Amazon-Events die ID der Conversion-Definition. Das Feld event_subtype trägt für Off-Amazon-Events numerische Werte, für On-Amazon-Events lesbare wie detailPageView, shoppingCart, order oder searchConversion.

Ad-attribuierte Conversions sind es, wenn dem User in den 28 Tagen vor dem Conversion-Event ein Traffic-Event ausgeliefert wurde. Genau diese 28 Tage sind der Grund, warum ein serverseitig gesendetes Event erst nach dieser Zeit als zugerechnet erscheint.

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

Wer dagegen eigene Conversion-Daten vollständig selbst in AMC analysieren will, nutzt den AMC-Datenupload (ADU). Der Unterschied: Über die Events API landen die Events in Amazon Ads und damit in den Berichten der Kampagnen; über ADU hochgeladene Conversions stehen ausschließlich in AMC zur Verfügung und können dort Zielgruppen erzeugen und an die DSP gesendet werden.

So prüfen Sie, ob Ihre Events ankommen

• Nach dem Senden können die Events bis zu zwei Stunden brauchen, bis sie in Ihrem Konto sichtbar sind. Amazon nennt diese Verzögerung ausdrücklich.
• Prüfen Sie im Events Manager: Registerkarte Conversions zeigt die gesendeten Events, die Gesamtzahl und die letzte Aktivität. Im Ads Data Manager erscheinen die Events zusätzlich als Conversion-Datasets.
• Achten Sie auf die Fehlerbilder aus der Amazon-Dokumentation: falsche Region in den Destination-Einstellungen, fehlende Berechtigungen im Amazon-Konto, Validierungsfehler, nicht akzeptierte Nutzungsbedingungen und eine falsche Advertiser-ID. Bei der Umstellung von CAPI v1 auf die Events API ist die häufigste Ursache eine Definition, die nur unter CAPI v1 angelegt wurde und im neuen Dataset-Kontext nicht mehr existiert.

Schritt für Schritt

1. Zugang und Konto-ID klären. Prüfen Sie, ob Sie über Login with Amazon auf ein DSP-Advertiser-Konto, ein globales Konto oder ein Manager-Konto zugreifen. Notieren Sie Client-ID, Advertiser-ID und die Region, in der das Konto liegt.
2. Consent-Pfad festlegen. Wählen Sie genau ein Signal: TCF, GPP oder das Amazon Consent Signal mit CountryCode, amzn_user_data und amzn_ad_storage. Für EU-Konten ist das Pflicht.
3. Dataset und Definition planen. Vergeben Sie einen sprechenden Dataset-Namen, zum Beispiel je Shop. Der Name ist unveränderlich und Teil des Eindeutigkeitskriteriums für Conversion-Definitionen.
4. Match-Keys normalisieren und hashen. Formatieren Sie E-Mail, Telefonnummer und Adressfelder nach den Amazon-Regeln und hashen Sie sie mit SHA-256. Geräte- und Plattform-IDs senden Sie ohne Hashing.
5. Deduplizierung mit dem Ad Tag abstimmen. Senden Sie dieselbe Aktion nicht doppelt: clientDedupeId im Tag und eventId im API-Aufruf mit identischem Wert.
6. Ergebnis prüfen. Warten Sie bis zu zwei Stunden und prüfen Sie im Events Manager die Registerkarte Conversions sowie die Spalte Excluded events. Danach in AMC die Tabelle conversions mit event_category = off-Amazon.

Häufige Fragen