Klaviyo

Die Klaviyo-Integration von Rekomi trägt jeden freigegebenen Affiliate in eine Klaviyo-Liste deiner Wahl ein und erfasst danach, soweit möglich (Best Effort), die Einwilligung ins E-Mail-Marketing.

Was synchronisiert wird

Sobald ein Affiliate freigegeben wird (oder optional schon bei seiner Bewerbung), führt Rekomi drei Schritte aus:

1. POST /api/profiles/ legt das Profil mit email, first_name, last_name an oder findet das passende (bei einer bestehenden E-Mail-Adresse kommt die ID des vorhandenen Profils zurück, es entsteht kein Duplikat).
2. Das Profil wird über den Endpunkt für Listenbeziehungen an deine gewählte Liste gehängt. Beide Schritte laufen synchron, ein „Erfolgreich“ in Rekomi heißt also, dass das Profil wirklich auf der Liste steht.
3. Best Effort: Ein Profile-Subscription-Job erfasst für das Profil auf dieser Liste die Einwilligung ins E-Mail-Marketing (SUBSCRIBED). Dieser Schritt läuft bei Klaviyo asynchron und lässt den Sync nie scheitern. Kann er nicht laufen, steht das Profil trotzdem auf der Liste, nur ohne erfasste Marketing-Einwilligung, und Klaviyo-Flows, die eine Einwilligung voraussetzen, überspringen es.

Zusammenspiel mit Double-Opt-in: Ist auf deiner Klaviyo-Liste Double-Opt-in aktiviert, löst Schritt 3 die Bestätigungs-E-Mail von Klaviyo aus, und der Affiliate muss darin klicken, bevor die Einwilligung erfasst wird. Bei Listen mit Single-Opt-in wird die Einwilligung sofort erfasst. Die Listenmitgliedschaft aus den Schritten 1 und 2 entsteht in jedem Fall.

Klaviyo entfernt Duplikate auf dem Server. Wird dieselbe E-Mail-Adresse erneut eingetragen, entsteht nie ein doppeltes Profil, die Attribute werden an Ort und Stelle aktualisiert.

API-Schlüssel finden

In Klaviyo:

1. Klicke oben rechts auf deinen Kontonamen.
2. Öffne Settings → API Keys.
3. Klicke auf Create Private API Key. Gib ihm einen Namen wie „Rekomi“.
4. Setze die Berechtigungen (Scopes), die Rekomi braucht:
   • Lists: Full Access (nötig für die Listenauswahl und das Eintragen in Listen).
   • Profiles: Full Access (nötig zum Anlegen und Aktualisieren von Profilen).
   • Subscriptions: Full Access (für den Best-Effort-Schritt zur Marketing-Einwilligung; der Sync klappt auch ohne, dann wird aber keine Einwilligung erfasst).
   • Accounts: Read Only (für den Verbindungstest; fehlt die Berechtigung, liest der Test ersatzweise einen einzelnen Listeneintrag).
5. Speichere und kopiere den erzeugten Schlüssel. Er beginnt mit pk_.

Wichtig: Die öffentliche Site ID (eine 6-stellige Zeichenfolge in deiner Klaviyo-URL) ist etwas anderes. Fügst du die öffentliche ID ein, verweigert Rekomi die Verbindung, denn das Formular prüft das Präfix pk_.

Klaviyo in Rekomi verbinden

1. Öffne Integrationen in der Seitenleiste des Dashboards.
2. Klicke auf die Karte von Klaviyo.
3. Füge deinen privaten API-Schlüssel ein. Klicke auf Verbinden.
4. Rekomi ruft GET /api/accounts/ auf (mit dem vorgeschriebenen Header revision, fest auf 2025-04-15), um den Schlüssel zu prüfen. Eingeschränkte Schlüssel ohne accounts:read sind in Ordnung, der Test liest dann ersatzweise einen einzelnen Listeneintrag.
5. Wähle im Dropdown Liste eine Standardliste. Die Listenauswahl fragt den Endpunkt /api/lists/ von Klaviyo ab, der höchstens 10 Einträge pro Seite liefert. Rekomi blättert über den Cursor in links.next und holt über mehrere Seiten bis zu 200 Listen.

Tags

Klaviyo kennt keine Tags in der Form, wie Mailchimp sie hat. Es arbeitet mit Listen, Profileigenschaften und Segmenten. Das Tag-Feld von Rekomi ist auf der Klaviyo-Karte deaktiviert, die Segmentlogik passiert in Klaviyo, nicht in Rekomi.

Um Profile aus Rekomi in Klaviyo zu erkennen, baue ein Segment, das nach der verbundenen Liste filtert (oder nach einer eigenen Profileigenschaft, die du selbst über die API von Klaviyo schreibst). Der System-Tag „Rekomi affiliate“ aus anderen CRMs lässt sich nicht sauber auf das Modell von Klaviyo übertragen.

Vermittelte Kunden und Leads (optional)

Schalte auf der Integrationsseite Vermittelte Kunden und Leads synchronisieren ein, dann schreibt Rekomi jeden Verkauf und jeden Lead, den es einem Affiliate zuordnet, auch nach Klaviyo. Der Abgleich läuft über die E-Mail-Adresse, bestehende Kontakte werden also aktualisiert statt doppelt angelegt. Jeder Eintrag enthält:

• die Profileigenschaften rekomi_referral_link, rekomi_campaign, rekomi_referring_affiliate, rekomi_referring_affiliate_code, rekomi_last_event, rekomi_last_sale_amount
• keine Tags (Klaviyo hat keine); baue ein Segment über rekomi_last_event
• Affiliates, die über den Abschnitt oben synchronisiert werden, bekommen in denselben Feldern zusätzlich Rekomi referral link, Rekomi campaign und Rekomi affiliate status, damit du den Link eines Affiliates in deine E-Mails einfügen kannst.

Erstattete, abgelehnte und wegen Betrugsverdacht in Quarantäne gestellte Conversions werden nie übertragen, importierte historische Conversions werden übersprungen. Die Option ist standardmäßig ausgeschaltet.

Wann synchronisiert wird

• Standard: Nur Affiliates mit dem Status Approved (freigegeben) werden synchronisiert.
• Optional: Schalte „Bewerber vor der Freigabe einschließen“ auf der Einstellungskarte des Anbieters ein, um Affiliates mit dem Status Pending (ausstehend) schon bei ihrer Bewerbung zu synchronisieren.

Einstellungen pro Kampagne

Jede Kampagne kann eine andere Klaviyo-Liste ansteuern oder Klaviyo ganz auslassen. Öffne den Tab Kampagneneinstellungen der Kampagne und scrolle zum Abschnitt CRM-Sync. Dort legst du fest:

• Eine eigene Liste für die Kampagne.
• Einen Schalter, der den Sync für diese Kampagne abschaltet.

Sync-Status pro Affiliate

Das Panel CRM-Sync auf der Detailseite eines Affiliates zeigt für jeden Affiliate den Status pro CRM, auch für Klaviyo. Der Button Erneut synchronisieren verwirft frühere Jobs und startet den Sync über den Worker neu.

Fehlerbehebung

• „Use the PRIVATE key (starts with 'pk_')“: Du hast die öffentliche Site ID eingefügt. Kopiere den Schlüssel erneut aus Klaviyo unter Settings → API Keys (den privaten Schlüssel, nicht die Site ID).
• „Listen konnten nicht geladen werden: 400, Page size must be an integer between 1 and 10“: Ein alter Rekomi-Build von vor der Korrektur. Dein aktueller Build blättert korrekt; wenn du das trotzdem siehst, lade die Seite ohne Cache neu.
• 403 beim Eintragen: Deinem privaten API-Schlüssel fehlt die Berechtigung Profiles: Full Access. Passe die Berechtigungen in Klaviyo an und klicke beim betroffenen Affiliate auf Erneut synchronisieren. Wiederholte Authentifizierungsfehler markieren die Integration außerdem mit „Aktion nötig“ und lösen eine E-Mail zum Neuverbinden aus. Nutze nach der Korrektur des Schlüssels Alle erneut synchronisieren auf der Kachel Fehlgeschlagen.
• Profil steht auf der Liste, aber Flows senden nicht daran: Das Profil kam über die synchronen Schritte an, die Marketing-Einwilligung wurde aber nicht erfasst. Entweder konnte der Einwilligungs-Job nicht laufen (die Berechtigung Subscriptions fehlt), oder deine Liste nutzt Double-Opt-in und der Affiliate hat noch nicht bestätigt. Prüfe den Einwilligungsstatus des Profils in Klaviyo.

Ein Hinweis zur API

Rekomi nutzt die JSON:API-Schnittstelle von Klaviyo (Revision 2025-04-15). Jede Anfrage muss Folgendes mitschicken:

• Authorization: Klaviyo-API-Key pk_...
• revision: 2025-04-15
• accept: application/vnd.api+json
• content-type: application/vnd.api+json (bei Schreibzugriffen)

Eckige Klammern in Query-Strings werden URL-kodiert (%5B und %5D), weil die Edge von Klaviyo wörtliche Klammern ablehnt. Für dich ändert das nichts, das alles passiert intern im Anbieter-Client von Rekomi.

Verbindung trennen

Klicke auf der Verbindungsseite von Klaviyo auf Trennen. Der Integrationseintrag und alle Einstellungen pro Kampagne werden gelöscht. Der bisherige Sync-Verlauf bleibt für Prüfzwecke erhalten.

---

Anwendungsfälle, passende Zielgruppen und besondere Automatisierungsmuster findest du im Überblick zur Klaviyo-Integration auf der Website.