Auf Lemon Squeezy installieren

Lemon Squeezy ist ein Merchant of Record, und Rekomi ist direkt damit integriert. Du fügst einen API-Schlüssel ein; Rekomi prüft ihn, legt den Webhook in deinem Store an und bestätigt, dass er registriert ist. Ab dann landen einmalige Bestellungen, erste Abo-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 Lemon Squeezy →.

Eine Sache vorab: API-Schlüssel von Lemon Squeezy laufen nach einem Jahr ab. Rekomi überwacht die Verbindung und bittet dich per E-Mail um ein Neuverbinden, wenn der Schlüssel nicht mehr funktioniert. Plane also einmal im Jahr 30 Sekunden für ein erneutes Einfügen ein.

Deinen Store verbinden

Schritt 1. Öffne in Lemon Squeezy Settings > API und klicke auf den Button +, um einen neuen API-Schlüssel zu erstellen. Kopiere ihn; Lemon Squeezy zeigt ihn nur einmal an.

Schritt 2. Öffne in Rekomi /dashboard/setup/lemonsqueezy und füge den Schlüssel ein. Rekomi prüft den Schlüssel, erkennt, ob er zum Testmodus oder zum Live-Modus gehört, und fragt, falls dein Konto mehr als einen Store hat, welchen du verbinden willst.

Schritt 3. Hat dein Konto mehr als einen Store, wähle den Store, den du tracken willst. Rekomi erzeugt ein Signing Secret und legt den Webhook in diesem Store für dich an und abonniert dabei genau die Ereignisse zu Bestellungen, Abonnements und Erstattungen, die es braucht. In der Webhook-Oberfläche von Lemon Squeezy musst du nichts einstellen, und beim Trennen in Rekomi wird der Webhook wieder gelöscht.

Attribution: rekomi_ref auf deine Checkouts setzen (Pflicht)

Lemon Squeezy hostet den Checkout auf der eigenen Domain, deshalb muss die Affiliate-Empfehlung vom Browser des Besuchers in den Bestelldatensatz gelangen. Dieser Schritt ist Pflicht: Ohne ihn kommen Bestellungen ohne Empfehlung an, und es wird keine Provision gutgeschrieben, es sei denn, die E-Mail-Adresse des Käufers passt zu einem Lead, der auf deiner Website erfasst wurde (der Fallback am Ende dieses Abschnitts).

Sorge zuerst dafür, dass das Rekomi-Tracking-Skript auf deiner Marketing-Website installiert ist, damit window.Rekomi.getReferral() einen Wert liefert, wenn ein Besucher über einen Affiliate-Link kommt. Das ist dasselbe Skript, das jede Rekomi-Installation nutzt; die Anleitung für deine Website-Plattform im Installations-Hub deckt es ab. Ein eigenes Skript für Lemon Squeezy brauchst du nicht: Die native Verbindung, die du oben eingerichtet hast, erfasst den Verkauf.

Setze die Empfehlung dann als checkout[custom][rekomi_ref] auf jeden Checkout-Link (Kaufen-Buttons, Links auf der Preisseite und das Overlay von Lemon.js nutzen alle dieselben URLs):

<script>
  document.addEventListener('DOMContentLoaded', function () {
    var ref = window.Rekomi && window.Rekomi.getReferral();
    if (!ref) return;
    document
      .querySelectorAll('a[href*="lemonsqueezy.com/buy/"], a[href*="lemonsqueezy.com/checkout"]')
      .forEach(function (a) {
        var url = new URL(a.href);
        url.searchParams.set('checkout[custom][rekomi_ref]', ref);
        a.href = url.toString();
      });
  });
</script>

window.Rekomi.getReferral() liefert die Empfehlung aus dem First-Party-Cookie, das das Head-Skript gesetzt hat. Lemon Squeezy übernimmt Werte aus checkout[custom][...] in die Custom Data der Bestellung, und genau dort liest der Webhook-Handler von Rekomi rekomi_ref aus.

Serverseitig erzeugte Checkouts. Erstellst du Checkouts serverseitig über die Checkouts API, übergib die Empfehlung stattdessen in checkout_data.custom:

{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "custom": { "rekomi_ref": "REFERRAL_FROM_YOUR_FRONTEND" }
      }
    }
  }
}

Lies die Empfehlung im Frontend mit window.Rekomi.getReferral() aus und schicke sie zusammen mit der Checkout-Anfrage an dein Backend.

Abgleich über die Lead-E-Mail (Fallback). Erreicht eine Bestellung Rekomi ohne rekomi_ref in ihrer Custom Data und enthält die Bestellung die E-Mail-Adresse des Käufers, 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 (das Tag, das Rekomi dir gibt, enthält data-rkmi-email-capture="auto" und erfasst damit die E-Mail-Adresse aus deinem Anmeldeformular als Lead; siehe Lead-Tracking), und schreibt dem Affiliate gut, der diesen Lead gebracht hat. Die Empfehlung in der Custom Data hat immer Vorrang, wenn sie vorhanden ist, genauso wie bei Verlängerungen der bisherige Verlauf des Kunden, und ein Affiliate, der mit seiner eigenen E-Mail-Adresse kauft, bekommt keine Gutschrift.

Was erfasst wird

• Einmalige Bestellungen werden beim Anlegen der Bestellung als einmalige Conversions erfasst.
• Erste Abo-Bestellungen werden einmal erfasst, als erste Conversion des Abonnements (Rekomi dedupliziert das Bestellereignis und das erste Zahlungsereignis, sodass nichts doppelt gezählt wird).
• Abo-Verlängerungen werden bei jeder erfolgreichen Verlängerungszahlung als wiederkehrende Conversions erfasst, sodass wiederkehrende Provisionen aus der Umsatzbeteiligung automatisch weiter auflaufen.
• Erstattungen, voll oder teilweise, holen die Provision automatisch und anteilig zurück, im selben Prüfpfad wie die ursprüngliche Conversion.
• Provisionen gelten vor Steuern. Lemon Squeezy ist ein Merchant of Record: Es zieht Umsatzsteuer und Mehrwertsteuer selbst ein, deshalb berechnet Rekomi die Provision auf die Bestellsumme abzüglich Steuer, und Rückforderungen bei Erstattungen werden auf derselben Basis vor Steuern bemessen. Affiliates verdienen am Verkauf, nie an der Steuer.

Fallback: Server-to-Server-Relay

Willst du die Strecke lieber selbst betreiben (zum Beispiel weil du schon einen Webhook-Consumer für Ereignisse von Lemon Squeezy hast), kannst du die native Verbindung auslassen und Ereignisse stattdessen an den HMAC-signierten S2S-Endpunkt von Rekomi weiterleiten: Abonniere order_created (plus subscription_payment_success für Verlängerungen und die Erstattungsereignisse), prüfe die X-Signature von Lemon Squeezy und sende den Verkauf per POST an Rekomi, mit der Affiliate-Empfehlung aus der Custom Data der Bestellung. Beträge in Webhook-Payloads von Lemon Squeezy sind bereits in Cent, multipliziere also nicht mit 100 (Payloads mit umgerechneter Währung können Nachkommastellen enthalten; runde auf ganze Cent). Die vollständige Endpunkt-Referenz, den Aufbau der Payload und den Erstattungs-Endpunkt findest du in der Dokumentation zur S2S-Tracking-API.

Rekomi verfolgt eine Abrechnungsquelle pro Workspace, deshalb schließt Lemon Squeezy Connect Stripe (über die Rekomi-App für Stripe), Paddle, Braintree, Shopify, Chargebee, Polar, Recurly, Gumroad, Creem, Dodo Payments, Mollie und die S2S-API aus (nativ und S2S eingeschlossen). Entscheide dich für eine maßgebliche Quelle für Verkäufe über Lemon Squeezy, damit Conversions nie doppelt erfasst werden, und trenne die eine Verbindung, bevor du eine andere herstellst.

Fehlerbehebung

Banner oder E-Mail „Deine Lemon-Squeezy-Verbindung ist unterbrochen.“ API-Schlüssel von Lemon Squeezy laufen nach einem Jahr ab, und das Löschen des Schlüssels in Lemon Squeezy hat sofort dieselbe Wirkung. Erstelle einen neuen Schlüssel unter Settings > API und füge ihn unter /dashboard/setup/lemonsqueezy ein; deine Tracking-Historie bleibt erhalten, und der Webhook wird automatisch neu angelegt.

Webhook fehlt oder wurde bearbeitet. Löscht oder bearbeitet jemand den Rekomi-Webhook in Lemon Squeezy, kommen keine Ereignisse mehr an (der Gesundheitscheck überwacht den API-Schlüssel, nicht den Webhook selbst). Trenne die Verbindung und verbinde sie auf der Einrichtungsseite mit einem aktuellen API-Schlüssel neu; beim erneuten Verbinden wird der Webhook automatisch neu angelegt.

Bestellungen kommen an, aber kein Affiliate erhält eine Gutschrift. Die Bestellung hat Rekomi ohne rekomi_ref in ihrer Custom Data erreicht. Prüfe, ob das Snippet zum Setzen der Empfehlung auf jeder Seite läuft, die auf den Checkout verlinkt, ob das Tracking-Skript lief, bevor der Käufer weitergeklickt hat (damit window.Rekomi.getReferral() einen Wert hat), und ob serverseitig erzeugte Checkouts checkout_data.custom.rekomi_ref übergeben.

Testbestellungen erscheinen nicht. Testmodus und Live-Modus sind Eigenschaften des API-Schlüssels, keine getrennten Hosts. Hast du einen Live-Schlüssel verbunden, werden Bestellungen im Testmodus nicht an den Webhook zugestellt, den Rekomi angelegt hat. Verbinde einen Schlüssel aus dem Testmodus mit einem Sandbox-Workspace, um den Ablauf von Ende zu Ende durchzuspielen.

Verwandte Seiten

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