Auf Paddle installieren

Paddle ist ein Merchant of Record: Dein Kunde bezahlt Paddle, und Paddle zahlt an dich aus. Rekomi ist direkt mit Paddle Billing integriert. Du richtest ein Notification-Ziel (Webhook) in Paddle direkt auf Rekomi und fügst dessen Signing Secret in dein Dashboard ein. Rekomi prüft jedes Ereignis und erfasst die Conversion, du musst also kein Backend-Relay bauen oder pflegen. Du bist noch am Abwägen? Lies Warum Rekomi für Paddle →.

Die Attribution hat zwei Hälften: Das Rekomi-Skript erfasst den Affiliate-Klick auf deinen Marketing-Seiten, und du gibst diese Empfehlung über customData an den Paddle Checkout weiter. Wenn Paddle die Bestellung an Rekomi sendet, wird die Empfehlung im Ereignis dem Affiliate zugeordnet.

Du nutzt einen eigenen Checkout oder eine andere Plattform? Nutze stattdessen die Server-to-Server-API. Über diesen Weg leitest du Conversions aus deinem eigenen Backend weiter.

1. Das Head-Skript installieren

Füge das Rekomi-Head-Skript in den <head> deiner Marketing-Website ein, und zwar auf jeder Seite, die zu einem Kauf führen kann. So wird der Klick erfasst, bevor der Käufer den Paddle Checkout öffnet.

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

In einem No-Code-Baukasten (Webflow, Framer, Squarespace usw.) nutzt du das Feld der Plattform für eigenen Head-Code. Die Programm-ID findest du im 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.

2. Die Empfehlung an den Paddle Checkout übergeben

Wenn du den Paddle Checkout öffnest, hängst du die Empfehlung aus window.Rekomi.getReferral() unter dem Schlüssel rekomi_ref an customData an. Paddle speichert sie in der Transaktion und schickt sie mit jedem Webhook zu dieser Bestellung mit.

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

Der Schlüssel in customData muss genau rekomi_ref lauten. Sein Wert ist der Link-Slug deines Affiliates, und mit diesem Slug gleicht Rekomi den Verkauf ab.

Abgleich über die Lead-E-Mail (Fallback). Erreicht eine abgeschlossene Transaktion Rekomi ohne rekomi_ref, gleicht Rekomi zusätzlich die E-Mail-Adresse des Käufers 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 Sache solltest du wissen: Die Standard-Notifications von Paddle enthalten unter Umständen nicht das Kundenobjekt, sondern nur die Kunden-ID, das Ereignis selbst trägt dann also keine E-Mail-Adresse. In diesem Fall liest Rekomi den Kunden über den Read-Only-API-Schlüssel von Paddle aus Schritt 5, vorausgesetzt, du hast einen gespeichert und nutzt die Lead-Erfassung. Der Fallback braucht also eines von beidem: das Kundenobjekt in der Notification oder den in Rekomi gespeicherten API-Schlüssel. Die Empfehlung in customData 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.

3. Deine Rekomi-Webhook-URL holen

Öffne in Rekomi Einrichtung, wähle Zahlungsanbieter verbinden und klicke auf Paddle verbinden. Rekomi zeigt eine Webhook-URL, die nur zu deinem Workspace gehört, zum Beispiel:

https://api.rekomi.com/api/webhooks/paddle/<your-token>

Kopiere sie. Diese URL gehört nur dir, und an ihr erkennt Rekomi, zu welchem Workspace ein Ereignis gehört. Gib sie nicht weiter.

4. Das Notification-Ziel in Paddle anlegen

Öffne in Paddle Developer tools → Notifications → New destination und füge die Rekomi-Webhook-URL ein. Aktiviere diese Ereignisse:

• transaction.completed
• subscription.created
• subscription.updated
• subscription.canceled
• adjustment.created
• adjustment.updated

Speichere das Ziel, öffne es dann erneut und kopiere sein Signing Secret (es beginnt mit pdl_ntfset_).

5. Das Signing Secret in Rekomi einfügen

Füge zurück in Paddle verbinden das Signing Secret ein, wähle deine Umgebung (Live oder Sandbox) und klicke auf Paddle verbinden. Mit diesem Signing Secret prüft Rekomi, dass jedes eingehende Ereignis wirklich aus deinem Paddle-Konto stammt. Es wird verschlüsselt gespeichert und nie wieder angezeigt.

Optional fügst du einen Read-Only-API-Schlüssel von Paddle ein (Developer tools → Authentication). Für das Tracking eines Verkaufs mit rekomi_ref brauchst du ihn nicht. Rekomi nutzt ihn, um die Verbindung beim Verbinden zu prüfen, für regelmäßige Gesundheitschecks, die bestätigen, dass die Verbindung in Ordnung ist, und um die E-Mail-Adresse des Käufers beim Kunden nachzulesen, wenn eine Notification sie nicht enthält und der Verkauf noch keinem Affiliate zugeordnet ist (der Abgleich über die Lead-E-Mail aus Schritt 2). Verpasste Ereignisse holt er nie nach. Das Tracking funktioniert auch nur mit dem Signing Secret.

Das war's. Ab jetzt wird jeder abgeschlossene Paddle-Verkauf mit rekomi_ref automatisch dem richtigen Affiliate gutgeschrieben.

Erstattungen

Erstattungen und Rückbuchungen werden automatisch verarbeitet, ohne zusätzliche Einrichtung. Wenn Paddle eine Erstattung oder eine Rückbuchung als Adjustment genehmigt (zugestellt über die Ereignisse adjustment.created / adjustment.updated), holt Rekomi die Provision anteilig zurück und aktualisiert das ausstehende Guthaben des Affiliates.

Gut zu wissen

Erfasse den Klick, bevor sich das Overlay öffnet. Das Overlay des Paddle Checkouts läuft in einem iframe, auf das Rekomi keinen Zugriff hat. Die Empfehlung muss deshalb schon erfasst sein (das Head-Skript muss gelaufen sein, und window.Rekomi.getReferral() muss einen Wert liefern), bevor der Käufer den Checkout öffnet. Bei Erstbesuchen, bei denen ein „Kaufen“-Button das Overlay sofort öffnet, ist der asynchrone Loader meist schnell genug. Siehst du trotzdem Lücken, öffne das Overlay erst etwa 200 ms nach dem Laden.

Beträge musst du nicht umrechnen. Paddle sendet Summen als Strings mit ganzzahligen Beträgen in der kleinsten Währungseinheit (zum Beispiel "4900" = $49.00), und Rekomi liest sie unverändert ein. Multipliziere sie nicht mit 100.

Provisionen werden auf den Betrag vor Steuern berechnet. Paddle ist ein Merchant of Record: Paddle zieht Sales Tax und Mehrwertsteuer selbst ein, dieses Geld ist also nie dein Umsatz. Rekomi berechnet die Provision auf die Transaktionssumme abzüglich ihrer Steuer und abzüglich eines Kundenguthabens, das Paddle verrechnet hat. Rückforderungen bei Erstattungen ziehen den Betrag der Erstattung vor Steuern ab und bleiben so genau spiegelbildlich zur Gutschrift. Deine Affiliates verdienen am Verkauf selbst, nie an der Steuer, die das Land des Käufers gerade aufschlägt.

Eine Conversion-Quelle pro Workspace. Paddle Connect schließt Stripe (über die Rekomi-App für Stripe), Braintree, Shopify, Lemon Squeezy, Chargebee, Polar, 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.

Fehlerbehebung

Ein Paddle-Verkauf ist nicht in Rekomi aufgetaucht. Prüfe drei Dinge: ob das Head-Skript auf der Seite läuft, die den Checkout öffnet, ob customData der Transaktion rekomi_ref mit dem Slug des Affiliates enthält und ob der Affiliate freigegeben ist. Das Notification-Protokoll von Paddle zeigt für jedes Ereignis die Zustellung und den Antwortcode von Rekomi.

Paddle zeigt einen 401 vom Webhook. Das Signing Secret in Rekomi fehlt oder passt nicht zum Ziel. Kopiere das Secret erneut aus dem Paddle-Ziel und verbinde neu. Ein in Paddle rotiertes Secret musst du in Rekomi neu einfügen. (Ein 404 bedeutet dagegen, dass der Token in der Webhook-URL veraltet ist. Verbinde neu, um die aktuelle URL zu bekommen.)

Die Verbindung wird in Rekomi als unterbrochen angezeigt. Das Ziel wurde entfernt oder sein Secret rotiert. Lege es in Paddle neu an oder kopiere das Secret erneut und verbinde dann auf der Seite „Paddle verbinden“ neu.

Verwandte Seiten

• Referenz der S2S-Tracking-API
• Leads und Anmeldungen tracken: Mit Paddle werden Anmeldungen für Abonnements und Testphasen automatisch als Leads erfasst, ohne zusätzlichen Code. Eine kostenlose Anmeldung, die nie ein Paddle-Abonnement anlegt, braucht weiterhin die Lead-API.
• Berichte in mehreren Währungen