Auf Polar installieren

Polar ist ein Merchant of Record: Dein Kunde bezahlt Polar, und Polar zahlt an dich aus. Es gibt also kein eigenes Stripe-Konto, das du verbinden müsstest. Rekomi ist direkt damit integriert, und für die Einrichtung fügst du nur einmal etwas ein: ein einziges Organization Access Token in Rekomi, den Rest erledigt Rekomi. Rekomi prüft das Token, ermittelt deine Organisation und legt den Webhook-Endpunkt selbst in deiner Polar-Organisation an. Du musst keinen Webhook von Hand konfigurieren und auf der Seite von Polar nichts einfügen. Ab dann fließen Bestellungen, Abo-Verlängerungen und Erstattungen in Rekomi, ohne dass du Relay-Code schreiben oder pflegen musst. Du bist noch am Abwägen? Lies Warum Rekomi für Polar →.

Was du brauchst

Ein Organization Access Token. Öffne in Polar deine Organization Settings, suche den Bereich Developers und erstelle ein Token mit genau diesen beiden Scopes:

• organizations:read
• webhooks:write

Stelle den Ablauf auf „No expiration“, damit die Verbindung nie nach einer festen Frist erlischt. Das Token beginnt mit polar_oat_. Rekomi legt damit den Webhook-Endpunkt an und führt Gesundheitschecks durch; Provisionen und Geldflüsse werden darüber nie berührt.

In Rekomi verbinden

Schritt 1. Öffne /dashboard/setup/polar und füge das Token ein.

Rekomi prüft das Token live, ermittelt deine Polar-Organisation und legt den Webhook-Endpunkt automatisch an. Er abonniert genau die Ereignisse, die Rekomi braucht:

• order.paid
• subscription.created
• subscription.canceled
• subscription.revoked
• subscription.uncanceled
• refund.created
• refund.updated

Polar erzeugt das Signing Secret des Webhooks, wenn der Endpunkt angelegt wird. Rekomi speichert es verschlüsselt und prüft bei jeder Zustellung die Signatur. Die Einrichtungsseite zeigt die URL und die Ereignisliste des Endpunkts nur zur Information.

Schritt 2. Mehr braucht die Verbindung nicht. Was noch fehlt, ist die Attribution: die Affiliate-Empfehlung in den Checkout zu bringen, wie unten beschrieben.

Attribution: die Empfehlung in den Checkout bringen

Polar hostet den Checkout auf seiner eigenen Domain, deshalb muss die Affiliate-Empfehlung vom Browser des Besuchers in die Bestellung gelangen. Für Checkout-Links und Embeds von Polar erledigt Rekomi das automatisch; nur serverseitig (per API) erstellte Checkouts brauchen eine kleine Ergänzung.

Sorge zuerst dafür, dass das Rekomi-Head-Skript auf deiner Marketing-Website installiert ist, damit der Affiliate-Klick erfasst wird, wenn ein Besucher über einen Affiliate-Link kommt:

<script async src="https://api.rekomi.com/api/v1/r/loader.js" data-program-id="YOUR_PROGRAM_ID" data-rkmi-email-capture="auto"></script>

Die Programm-ID findest du im Rekomi-Dashboard unter Einstellungen, Tracking, Website-Snippet (der Installationsbereich). Rekomi erfasst eine E-Mail-Adresse, die ein vermittelter Besucher auf den Seiten, auf denen das Tag läuft, in ein beliebiges E-Mail- oder Textfeld tippt (Registrierung, Login, Checkout und andere Formulare), damit der Verkauf auch dann gutgeschrieben werden kann, wenn dein Checkout keine Empfehlung übergibt. Ohne Empfehlung wird nichts erfasst. Entferne das Attribut data-rkmi-email-capture, um das auszuschalten; explizite Aufrufe von Rekomi.convert() funktionieren weiterhin.

Checkout-Links und Embeds (automatisch, nichts zu ergänzen). Verkaufst du über Checkout-Links oder Embed-Buttons von Polar (buy.polar.sh / polar.sh/checkout), erledigt das Rekomi-Skript oben den Rest: Es hängt die reference_id des Affiliates für dich an diese Links an, sowohl beim Laden der Seite als auch erst im Moment des Klicks (so funktionieren auch dynamisch eingefügte Links und Links in Single-Page-Apps). Polar übernimmt reference_id in metadata.reference_id der Bestellung, und dort liest Rekomi sie für die Attribution aus. Trägt ein Link schon eine reference_id, lässt Rekomi deinen Wert stehen, statt ihn zu überschreiben.

Serverseitig erstellte Checkouts über die API von Polar (eine kleine Ergänzung). Wenn dein Backend den Checkout erstellt, kommt das Client-Skript nicht daran heran. Setze metadata.rekomi_ref (den maßgeblichen Schlüssel) deshalb selbst. Lies die Empfehlung im Frontend mit window.Rekomi.getReferral() aus und schick sie mit der Checkout-Anfrage mit:

const ref = window.Rekomi && window.Rekomi.getReferral();
await polar.checkouts.create({
  products: ["your-product-id"],
  metadata: ref ? { rekomi_ref: ref } : {},
});

Rekomi liest zuerst metadata.rekomi_ref, dann metadata.reference_id. Nutzt du reference_id schon für deine eigene Buchhaltung, bleib dabei: Ein Wert, der zu keinem Affiliate passt, wird einfach ignoriert, und der Schlüssel rekomi_ref bleibt frei für die Attribution.

Abgleich über die Lead-E-Mail (Fallback). Erreicht eine Bestellung Rekomi weder mit rekomi_ref noch mit einer reference_id, die zu einem Affiliate passt, und enthält die Bestellung die E-Mail-Adresse des Kunden, gleicht Rekomi diese Adresse zusätzlich mit den Leads ab, die das Rekomi-Skript in den letzten 90 Tagen auf deiner eigenen Website erfasst hat (schalte die E-Mail-Erfassung in deinem Registrierungsformular mit data-rkmi-email-capture="auto" am Loader-Tag ein; siehe Lead-Tracking), und schreibt dem Affiliate gut, der diesen Lead gebracht hat. Eine Empfehlung in den Metadaten hat immer Vorrang, wenn sie vorhanden ist, genauso wie der bisherige Verlauf des Kunden, und ein Affiliate, der mit seiner eigenen E-Mail-Adresse kauft, bekommt keine Gutschrift.

Was erfasst wird

• Bestellungen werden erfasst, wenn order.paid ausgelöst wird: Ein Erstkauf ist eine einmalige Conversion, Abo-Verlängerungen sind wiederkehrende Conversions, sodass wiederkehrende Provisionen auf Umsatzbeteiligung automatisch weiterlaufen. Die beim Checkout gesetzte Empfehlung bleibt am Abonnement, Verlängerungen werden also demselben Affiliate gutgeschrieben; zusätzlich greift Rekomi auf die Conversion-Verlauf des Kunden zurück.
• Grundlage der Provision ist der Nettobetrag der Bestellung: nach Rabatten, ohne Steuer (Polar zieht als Merchant of Record die Steuer ein; auf sie gibt es nie Provision) und abzüglich eines Kundenguthabens, das Polar verrechnet hat. Testphasen erzeugen zu Beginn eine Bestellung über $0, die nie eine Provision bringt. Ist die Empfehlung zugeordnet, erfasst Rekomi sie als Lead über $0 (sichtbar in deinem Funnel und in den Lead-Ansichten), und die Provision entsteht mit der ersten echten Zahlung.
• Ereignisse im Lebenszyklus eines Abonnements (angelegt, gekündigt, widerrufen, Kündigung zurückgenommen) werden im Verlauf des Abonnements erfasst. So siehst du Kündigungen und Reaktivierungen direkt neben den Conversions. Provisionen werden nur bei einer Erstattung zurückgeholt.
• Erstattungen, ob vollständig oder teilweise, holen die Provision automatisch und anteilig zurück, im selben Prüfprotokoll wie die ursprüngliche Conversion. Der erstattete Betrag ist ein Betrag vor Steuern, spiegelbildlich zur Grundlage der Provision.

Erstattungen und Rückbuchungen

Erstattungen, die du in Polar auslöst, kommen als Erstattungsereignisse an und holen die Provision anteilig zurück: Eine Erstattung von 40% holt 40% der Provision zurück. Ausstehende Erstattungen werden erst zurückgeholt, wenn sie erfolgreich sind. Ein Vorbehalt: Polar sendet keinen Webhook für Streitfälle oder Rückbuchungen, und ein verlorener Streitfall taucht nicht als Erstattungsereignis auf. Er erreicht Rekomi also nie von selbst. Kommt es zu einer Rückbuchung, erklärst du die Conversion manuell für ungültig, und die Provision wird im selben Prüfprotokoll zurückgeholt.

Sicherheit

• Jede Webhook-Zustellung wird mit dem von Polar erzeugten Signing Secret geprüft (HMAC-Signaturen nach dem Standard-Webhooks-Schema mit einem Replay-Fenster von 5 Minuten), bevor irgendetwas verarbeitet wird. Zustellungen, die die Prüfung nicht bestehen, werden abgelehnt.
• Dein Organization Access Token und das Signing Secret des Webhooks werden verschlüsselt gespeichert und nie von der API zurückgegeben. Beim Trennen werden beide gelöscht, der von Rekomi in deiner Polar-Organisation angelegte Webhook-Endpunkt wird entfernt, und die URL deines Workspaces wird stillgelegt.
• Die beiden Scopes des Tokens erlauben nur, deine Organisation zu lesen und ihren Webhook-Endpunkt zu verwalten. Rekomi ändert in deinem Polar-Konto nie Produkte, Preise oder Auszahlungen.

Gut zu wissen

• Eine Conversion-Quelle pro Workspace. Polar Connect schließt Stripe (über die Rekomi-App für Stripe), Paddle, Braintree, Shopify, Lemon Squeezy, Chargebee, Recurly, Gumroad, Creem, Dodo Payments, Mollie und die S2S-API aus, damit derselbe Verkauf nie doppelt gezählt wird. Trenne die eine Verbindung, bevor du eine andere herstellst.
• Tokens müssen nicht ablaufen. Wähle beim Erstellen des Tokens „No expiration“. Wird das Token irgendwann widerrufen, markiert der Gesundheitscheck die Verbindung als unterbrochen, zeigt ein Banner zum Neuverbinden und schickt dir eine E-Mail. Mit einem neuen Token stellst du die Verbindung wieder her, und dein Verlauf bleibt erhalten.
• Polar deaktiviert fehlerhafte Endpunkte automatisch. Nach wiederholt fehlgeschlagenen Zustellungen deaktiviert Polar einen Webhook-Endpunkt. Der Gesundheitscheck von Rekomi erkennt genau diesen Zustand: Aktiviere den Endpunkt in den Webhook-Einstellungen von Polar wieder oder verbinde einfach in Rekomi neu (dabei wird der Endpunkt frisch angelegt).
• Beim Neuverbinden wird das Secret rotiert. Ein Neuverbinden löscht den alten Endpunkt und legt einen neuen an, für den Polar ein neues Signing Secret erzeugt. Du musst nichts von Hand kopieren.
• Die Sandbox ist eine eigene Welt. Die Sandbox von Polar (sandbox.polar.sh) hat eigene Konten und Tokens. Rekomi in der Produktion akzeptiert nur Produktions-Tokens; ein Sandbox-Token, das du in der Produktion einfügst, besteht die Prüfung nicht und wird abgelehnt.

Fehlerbehebung

Banner „Deine Polar-Verbindung ist unterbrochen.“ oder E-Mail zum Neuverbinden. Entweder ist das gespeicherte Token nicht mehr gültig (in Polar widerrufen oder abgelaufen), oder der Webhook-Endpunkt wurde gelöscht oder deaktiviert. Verbinde unter /dashboard/setup/polar mit einem neuen Organization Access Token neu; dein Tracking-Verlauf bleibt erhalten.

Polar hat den Webhook-Endpunkt deaktiviert. Polar schaltet einen Endpunkt nach wiederholt fehlgeschlagenen Zustellungen ab. Aktiviere ihn in Polar unter Organization Settings > Webhooks wieder oder verbinde in Rekomi neu, um ihn neu anzulegen. Die Verbindungsprüfung auf der Einrichtungsseite sagt dir, wenn das der Grund ist.

„Required events missing“ (benötigte Ereignisse fehlen) beim Gesundheitscheck. Jemand hat die Ereignisliste des Webhooks im Dashboard von Polar bearbeitet, und der Endpunkt abonniert nicht mehr alles, was Rekomi braucht. Klicke auf der Einrichtungsseite auf Neu verbinden; dabei wird der Endpunkt mit allen Ereignissen neu angelegt.

Bestellungen kommen an, aber kein Affiliate bekommt eine Gutschrift. Die Bestellung hat Rekomi ohne Empfehlung in den Metadaten erreicht. Prüfe, ob das Rekomi-Head-Skript installiert ist und gelaufen ist, bevor der Käufer weitergeklickt hat (damit window.Rekomi.getReferral() einen Wert hat), und ob serverseitig (per API) erstellte Checkouts metadata.rekomi_ref setzen. Checkout-Links und Embeds von Polar markiert das Skript automatisch. Dort liegt es also meist daran, dass das Head-Skript auf der Seite, die zum Checkout verlinkt, schlicht fehlt.

Das Token wird beim Verbinden abgelehnt. Prüfe, ob das Token vollständig kopiert wurde (es beginnt mit polar_oat_), ob es die Scopes organizations:read und webhooks:write hat und ob es weder abgelaufen noch widerrufen ist.

Verwandte Seiten

• Referenz der S2S-Tracking-API
• Checkout-Tracking ohne Code und ohne Stripe
• Umgang mit Erstattungen