Affiliate-Tracking mit Paddle: So funktioniert die Attribution auf Paddle Billing

Affiliate-Tracking mit Paddle funktioniert so: Die Empfehlung des Affiliates reist als Custom Data in den Paddle Checkout mit und wird aus den signierten Webhooks von Paddle wieder ausgelesen, sobald tatsächlich Geld fließt. Paddle selbst übernimmt davon nichts (es ist ein Merchant of Record, keine Affiliate-Plattform). Ein Tracking-Tool liefert also die Links, die Berechnung der Provisionen und die Auszahlungen, und Paddle liefert zwei wirklich gute Bausteine: ein Feld customData, das für immer an der Transaktion bleibt, und Webhooks, die jeden Verkauf, jede Verlängerung, jede Erstattung und jede Rückbuchung melden.

Dieser Artikel geht die ganze Runde durch: den Klick, die Übergabe an den Checkout, den Webhook, der zurückkommt, und die Rückforderungen, wenn es Erstattungen gibt. Bei jedem Schritt nenne ich die genauen Felder und Ereignisse, denn bei der Attribution geht es um die Technik darunter, und wenn die unsauber ist, fragen in deinem Programm irgendwann Affiliates, wo ihre Provision geblieben ist.

Eine nützliche Info vorweg: Den Webhook-Handler von Rekomi für Paddle habe ich selbst geschrieben. Was folgt, beschreibt also Code, den ich pflege, und keine Spezifikation, die ich nur überflogen habe. Das heißt auch, dass du mich beim Wort nehmen kannst: Jede Aussage unten lässt sich in der Entwicklerdokumentation von Paddle nachprüfen, und ich kann dir nur empfehlen, dort nachzusehen.

Die ganze Runde im Überblick:

Der Klick: Ein einzeiliges Skript speichert den Link-Slug des Affiliates für 90 Tage im Browser des Besuchers und protokolliert den Klick auf dem Server.

Die Übergabe: Dein Checkout-Aufruf gibt customData: { rekomi_ref: ... } mit, und Paddle speichert diesen Wert an der Transaktion und an dem Abonnement, das daraus entsteht.

Das Geld: Jeder Webhook transaction.completed (Erstverkäufe genauso wie Verlängerungen) bringt die Custom Data mit geprüfter Signatur zurück, und die Provision wird auf den Betrag vor Steuern verbucht.

Das Aufräumen: Adjustments für Erstattungen und Rückbuchungen stornieren die Provision automatisch, sobald Paddle sie genehmigt.

Übernimmt Paddle das Affiliate-Tracking selbst?

Nein. Paddle kümmert sich um Checkout, Abrechnung und die Steuerlast als Merchant of Record und hört dort ganz bewusst auf: keine Empfehlungslinks, kein Provisionssystem, kein Affiliate-Dashboard. Was Paddle dafür liefert, ist genau das Rohmaterial, das Tracking braucht. Deshalb ist jedes ernsthafte Affiliate-Tool auf Paddle im Kern so aufgebaut, wie du es gleich siehst.

Zwei Abgrenzungen, damit wir vom selben Artikel sprechen. Den Aufbau des Programms (Provisionsstruktur, das Gewinnen von Affiliates, Auszahlungswege, die W-9-Formulare) behandelt der Leitfaden So richtest du ein Paddle-Affiliate-Programm ein, und wenn du noch nach Software suchst, vergleicht die Übersicht der besten Affiliate-Software für Paddle sechs Optionen ehrlich. Hier geht es darum, was unter der Haube passiert, sobald ein Tool verbunden ist.

Die Klick-Hälfte: Alles beginnt auf deiner Website

Dein Affiliate teilt einen Link wie yoursite.com?via=jess. Ein kleines Skript im <head> deiner Website (das von Rekomi ist buchstäblich eine Zeile) erledigt beim Laden der Seite zwei Aufgaben:

• Es speichert die Empfehlung im Browser. Der Slug jess landet mit 90 Tagen Laufzeit im Local Storage, dazu kommt ein First-Party-Cookie, wenn eine eigene Tracking-Domain eingerichtet ist. Das Skript erkennt standardmäßig 19 Attributionsparameter (?via=, ?ref=, ?fpr= und die anderen Dialekte, die sich die Branche ausgedacht hat), Links aus einem früheren Tool funktionieren nach einem Umzug also weiter.
• Es protokolliert den Klick auf dem Server. Referrer, UTM-Parameter, optional eine Sub-ID. Damit lässt sich später die Lieblingsfrage jedes Affiliates beantworten: Welcher meiner Beiträge bringt wirklich Verkäufe?

Klickt derselbe Besucher auf die Links von zwei verschiedenen Affiliates, überschreibt der neuere Klick den älteren. Der letzte Klick gewinnt, und genau das erwarten Affiliates ohnehin.

Und dir fällt sicher auf, dass Paddle bisher gar nicht vorkommt. Die Empfehlung liegt einfach im Browser und wartet auf einen Kauf-Button.

Die Übergabe: rekomi_ref reist in den customData mit

So funktioniert es: Wenn deine Website den Paddle Checkout öffnet, hängst du die gespeicherte Empfehlung unter genau einem Schlüssel an die Custom Data des Checkouts, rekomi_ref.

const referral = window.Rekomi && window.Rekomi.getReferral();
Paddle.Checkout.open({
  items: [{ priceId: 'pri_xxx', quantity: 1 }],
  customData: { rekomi_ref: referral || null },
});

Ein Schlüssel, ein paar Zeilen, und die Übergabe ist erledigt! Paddle macht damit etwas ganz unauffällig Hervorragendes: Custom Data, die beim Checkout mitgegeben werden, bleiben an der Transaktion gespeichert, werden auf das Abonnement kopiert, das diese Transaktion anlegt, und von dort wieder auf jede spätere Transaktion des Abonnements, Verlängerungen und Upgrades eingeschlossen. Hinterleg den Slug einmal, und er taucht bei jeder Zahlung wieder auf. Nachprüfen kannst du das in der Dokumentation von Paddle zu Custom Data.

Eine Eigenheit beim Timing, die du beachten solltest: Der Paddle Checkout läuft in einem iframe, auf das die Skripte deiner Seite keinen Zugriff haben. Die Empfehlung muss also schon erfasst sein, bevor der Käufer das Overlay öffnet. Der asynchrone Loader ist fast immer schnell genug. Wenn ein neuer Besucher aber schon in der ersten Sekunde nach dem Laden der Seite auf „Buy“ klicken kann und dir Verkäufe durchrutschen, öffne das Overlay mit etwa 200ms Verzögerung.

Die Webhook-Hälfte: sechs Ereignisse, eines davon mit Geld

Auf der Seite von Paddle richtest du eine Notification Destination auf die Webhook-URL des Tracking-Tools und aktivierst sechs Ereignisse: transaction.completed, subscription.created, subscription.updated, subscription.canceled, adjustment.created und adjustment.updated. Einen Relay-Server musst du nicht bauen, denn Paddle spricht direkt mit dem Tool.

Das Geldereignis: transaction.completed. Auf Paddle ist alles, was eine Karte belastet, eine Transaktion: Erstkäufe, Abo-Verlängerungen, einmalige Add-ons. Dieses eine Ereignis trägt also jeden Dollar. Wenn es ankommt, liest das Tool custom_data.rekomi_ref aus und gleicht den Slug mit einem freigegebenen Affiliate ab. Kein Treffer? Dann prüft es, ob diese Paddle-customer_id schon einen zugeordneten Kauf hat (das Netz der Kundenhistorie fängt die Grenzfälle auf), und wenn auch das nicht klappt, wird der Verkauf ohne Zuordnung erfasst und wartet in einer Prüfliste, statt dass geraten wird.

Die Ereignisse im Lebenszyklus: subscription.created legt eine Anmeldezeile mit $0 an, damit dein Dashboard das vermittelte Abonnement vom ersten Tag an zeigt, und subscription.updated / subscription.canceled sorgen dafür, dass der Status des Kunden aktuell bleibt. Keines davon bewegt Geld, das tun die Transaktionen.

Die Ereignisse zum Aufräumen: die beiden Adjustment-Ereignisse, die unten einen eigenen Abschnitt bekommen.

Und bevor irgendetwas davon läuft, wird jede Zustellung authentifiziert. Paddle signiert jeden Webhook mit einem Header Paddle-Signature: einem Zeitstempel plus einem HMAC-SHA256 über {timestamp}:{raw body}, berechnet mit dem Secret pdl_ntfset_ der Notification Destination, in einem Format, das die Dokumentation von Paddle zur Signaturprüfung genau beschreibt. Rekomi prüft diese Signatur mit einem Vergleich in konstanter Zeit, lehnt Ereignisse außerhalb eines Replay-Fensters von 5 Minuten ab und verarbeitet jede event_id genau einmal. Eine wiederholte Zustellung kann eine Provision also nie doppelt gutschreiben. Diese Ebene des Systems mag ich ehrlich gesagt besonders: Niemand sieht sie je, und sie ist der Grund, warum du den Zahlen vertrauen kannst.

Verlängerungen: ein Klick, wiederkehrende Provisionen

Was passiert also im zweiten Monat? Paddle erzeugt eine Verlängerungstransaktion, die Custom Data des Abonnements werden darauf kopiert, und transaction.completed kommt fast genauso an wie beim ersten Verkauf. Das Tool schreibt demselben Affiliate die Provision automatisch wieder gut, in jedem Zyklus.

Das Rechnen ist der schöne Teil. Ein Produkt für $49/Monat mit 20% wiederkehrender Provision bringt dem Affiliate $9.80 beim ersten Verkauf und $9.80 bei jeder Verlängerung danach: Zwölf Monate Kundenbindung machen aus einem vermittelten Klick $117.60. Niemand muss irgendetwas zweimal hinterlegen, und kein Job prüft Cookies erneut. Die Vererbung der Metadaten erledigt die ganze Arbeit!

Und selbst wenn die Custom Data bei einer Verlängerung einmal fehlen sollten, würde der Fallback über die Kundenhistorie sie trotzdem auffangen: dieselbe customer_id, derselbe Affiliate.

Erstattungen, Rückbuchungen und die Eigenheit beim Merchant of Record

Geld, das wieder hinausgeht, bildet Paddle Billing als Adjustments ab, und genau hier unterscheidet sich eine sorgfältige Umsetzung von einer naiven. Drei Details zählen:

• Nur echter Geldabfluss führt zu einer Rückforderung. Zu den Adjustment-Aktionen von Paddle gehören refund, credit, chargeback und ein paar Varianten der Stornierung. Nur Erstattungen und Rückbuchungen stornieren Provisionen; bei einer Credit Note fließt kein Geld ab.
• Nur genehmigte Adjustments führen zu einer Rückforderung. Paddle legt die meisten Erstattungen als pending_approval an und prüft sie, bevor es sie genehmigt oder ablehnt. Würde die Provision schon beim Anlegen zurückgeholt, würde das einen Affiliate für einen Erstattungsantrag bestrafen, der am Ende abgelehnt wird. Die Provision wird deshalb erst storniert, wenn der Status approved erreicht. Dass das Tool auf adjustment.created und adjustment.updated hört, sorgt dafür, dass dieser Übergang ankommt, und jedes Adjustment wirkt genau einmal, egal wie oft Paddle es zustellt.
• Teilerstattungen wirken anteilig. Eine Erstattung von $15 auf einen Verkauf über $60 holt genau ein Viertel der Provision zurück, und im Provisionsbuch des Affiliates steht die Zeile dazu.

Jetzt zur Eigenheit bei den Steuern. Paddle ist ein Merchant of Record: Es zieht die Mehrwertsteuer oder Sales Tax des Käufers selbst ein, und diese Steuer war nie dein Umsatz. Provisionen werden deshalb auf den Betrag vor Steuern berechnet, also die Summe der Transaktion abzüglich der Steuer und abzüglich eines Kundenguthabens, das Paddle verrechnet hat. Konkret: Ein Checkout über $60, in dem $10 Mehrwertsteuer stecken, bringt einem Affiliate mit 25% dann $12.50 (25% von $50) und nicht $15. Auch Rückforderungen bei Erstattungen ziehen nur den Anteil der Erstattung vor Steuern ab, damit die Stornierung genau spiegelt, was gutgeschrieben wurde. Deine Affiliates verdienen am Verkauf, und die Steuerbehörde des Käufers spielt dabei überhaupt keine Rolle.

Warum Gutscheincodes auf Paddle nicht zugeordnet werden

Ich will das nicht schönreden: Auf dem Paddle-Weg von Rekomi ordnet ein Rabattcode eines Affiliates allein keinen Verkauf zu. Der Grund ist ein Detail in der Payload von Paddle plus ein ehrlicher Kompromiss auf unserer Seite. Der Webhook von Paddle meldet den Rabatt als discount_id (eine Kennung dsc_...) und nicht als den Code, den der Käufer eingetippt hat. Um ihn wieder dem Code eines Affiliates zuzuordnen, müsste das Tool beim Verbuchen der Conversion die API von Paddle aufrufen. Bei diesem Kompromiss war ich mehr als einmal hin- und hergerissen und habe mich klar dagegen entschieden: Der Weg, auf dem Rekomi Conversions verbucht, ruft die API von Paddle bewusst kein einziges Mal auf. So kann ein Ausfall der Paddle-API nie verhindern, dass geprüfte Verkäufe verbucht werden. Die Zuverlässigkeit hat gewonnen, und ehrlich gesagt verstand sich das von selbst.

Auf Paddle gilt also: Links tragen die Attribution, die Kundenhistorie sichert sie ab, und eine reine Code-Aktion (ein Influencer sagt „nutz JESS10“, ohne dass ein Klick dahintersteht) wird nur zugeordnet, wenn der Käufer vorher geklickt hat oder du den Verkauf von Hand aus der Prüfliste gutschreibst. Wenn die Attribution über Codes das Herzstück deines Programms ist, ist Stripe der Zahlungsanbieter, bei dem das vollständig funktioniert. Auf Paddle sind Gutscheine ein Rabatt und kein Tracking-Werkzeug.

Ein Hinweis zu Paddle Classic

Alles oben beschreibt Paddle Billing. Classic ist eine frühere Produktgeneration mit einem anderen Webhook-Vertrag: Es signiert mit p_signature und kennt kein customData in dieser Form. Rekomi unterstützt nur Billing. Wenn du auf Classic bist und den Umzug planst, rechne damit, das Tracking im Zuge des Umzugs neu anzubinden, statt davon auszugehen, dass sie einfach mitkommt.

Was deine Affiliates sehen, während das alles läuft

Der Lohn für die ganze Technik ist ein langweiliges, vertrauenswürdiges Dashboard. Jeder Affiliate sieht seine Klicks, seine Conversions, die mit den Webhooks eintreffen, und ein ausstehendes Guthaben, das mit jeder Verlängerung ein Stück wächst. Stornierungen nach Erstattungen erscheinen als einzelne Zeilen statt als stille Abzüge, und das tut mehr für das Vertrauen deiner Affiliates als jede FAQ-Seite. Und wenn aus Guthaben Auszahlungen werden, bewegt Rekomi das Geld selbst, in 130+ Ländern (Stripe Express in 41 Ländern, per Banküberweisung in 60 weiteren, per PayPal in 31 weiteren), Steuerformulare inklusive.

Kurze Antworten zum Affiliate-Tracking mit Paddle

Hat Paddle ein eingebautes Affiliate-Tracking?

Nein. Paddle stellt Felder für Custom Data und signierte Webhooks bereit; Affiliate-Links, die Berechnung der Provisionen und die Auszahlungen kommen von einem Tracking-Tool, das darauf aufbaut.

Welches Webhook-Ereignis von Paddle löst eine Provision aus?

transaction.completed. Es löst bei Erstkäufen und jeder Verlängerung aus, bringt die Custom Data des Checkouts mit und meldet Beträge als ganzzahlige Strings in kleinsten Einheiten, „4900“ bedeutet also $49.00, ganz ohne Umrechnung.

Bringen Abo-Verlängerungen dem Affiliate weiter Provision?

Ja. Paddle kopiert die Custom Data des Checkouts auf das Abonnement und von dort auf jede Verlängerungstransaktion. Jeder Zyklus wird also dem ursprünglichen Affiliate gutgeschrieben, mit der Kundenhistorie als Fallback.

Kann ich Paddle-Affiliates über Gutscheincodes nachverfolgen?

Nein, nicht als eigenständiges Signal. Die Webhooks von Paddle melden eine discount_id statt des eingelösten Codes, Verkäufe nur mit Gutschein werden auf Paddle also nicht zugeordnet. Nutze Links als wichtigsten Mechanismus.

Wann holt eine Erstattung die Provision zurück?

Wenn Paddle das Adjustment genehmigt. Ausstehende Erstattungen stornieren nichts, abgelehnte nie, und genehmigte Erstattungen und Rückbuchungen stornieren die Provision anteilig auf Basis des Betrags vor Steuern.

Spiel die Runde einmal in der Sandbox durch

Vertrauen ins Tracking entsteht, wenn du zusiehst, wie es einen Verkauf auffängt, und Paddle macht die Generalprobe super einfach. Verbinde ein Paddle-Sandbox-Konto mit der Paddle-Integration, klick auf deinen eigenen Testlink, mach einen Sandbox-Checkout mit hinterlegtem rekomi_ref und sieh zu, wie die Conversion mit dem Namen des richtigen Affiliates ankommt. Die Sandbox genehmigt Erstattungen sogar alle zehn Minuten automatisch, du kannst also auch zusehen, wie die Rückforderung auslöst. Fünfzehn Minuten, und aus der Runde wird statt eines Artikels, den du gelesen hast, etwas, das du selbst hast laufen sehen!