Auf Gumroad installieren

Gumroad ist ein Merchant of Record für digitale Produkte und Mitgliedschaften, und Rekomi ist direkt damit integriert, mit dem einfachsten Verbindungsablauf aller Anbieter: einem Klick. Du klickst auf Gumroad verbinden, bestätigst Rekomi einmal im Zustimmungsdialog von Gumroad (Lesezugriff auf Verkäufe), und Rekomi registriert die Benachrichtigungen für Verkäufe, Erstattungen, Streitfälle und den Lebenszyklus von Mitgliedschaften selbst in deinem Gumroad-Konto. Du musst keine Ping URL konfigurieren, keinen Webhook einfügen und keinen Relay-Code schreiben oder pflegen. Du bist noch am Abwägen? Lies Warum Rekomi für Gumroad →.

In Rekomi verbinden

Schritt 1. Klicke auf Gumroad verbinden, entweder im Einrichtungsschritt Zahlungsanbieter verbinden oder unter /dashboard/setup/gumroad. Der Button startet die OAuth-Autorisierung direkt: ein Klick, keine Zwischenseite, und du bist im Zustimmungsdialog von Gumroad, der nur nach Lesezugriff auf Verkäufe fragt (view_sales).

Schritt 2. Bestätige. Du landest wieder auf /dashboard/setup/gumroad, schon verbunden (dort verwaltest du die Verbindung auch später): Rekomi ermittelt deine Verkäuferidentität und registriert sechs Ressourcen-Abonnements in deinem Gumroad-Konto (sale, refund, dispute, cancellation, subscription_ended, subscription_restarted). Die Einrichtungsseite zeigt sie als Chips an, damit du siehst, dass alle sechs aktiv sind.

Erweiterter Fallback: ein Zugriffstoken einfügen. Kannst du den Ablauf über den Button nicht nutzen, gibt es auf der Einrichtungsseite einen eingeklappten Bereich „Erweitert“. Dort kannst du ein Zugriffstoken aus einer Anwendung einfügen, die du in Gumroad anlegst (Settings > Advanced > Applications). Der Haken dabei: Ein so erstelltes Token gibt Zugriff auf dein gesamtes Gumroad-Konto, nicht nur auf die Verkäufe. Deshalb ist der Button „Verbinden“ (beschränkt auf view_sales) der empfohlene Weg. So oder so wird das Token verschlüsselt gespeichert und nie wieder angezeigt.

Verbinden darf in Rekomi nur der Owner, und neu verbinden ist jederzeit gefahrlos: Rekomi räumt seine alten Registrierungen auf und rotiert deine Webhook-Zugangsdaten automatisch.

Attribution: der Link-Parameter rekomi_ref

Gumroad hostet seinen Checkout auf der eigenen Domain, deshalb reist die Affiliate-Empfehlung als Query-Parameter am Produktlink mit: ?rekomi_ref=AFFILIATE_SLUG oder ?via=AFFILIATE_SLUG (Rekomi liest beide). Gumroad überträgt die Query-Parameter der Landing-URL in die Verkaufsbenachrichtigung, und daran erkennt Rekomi, welcher Affiliate den Verkauf gebracht hat.

• Von Rekomi erzeugte Affiliate-Links tragen die Empfehlung automatisch. Von Rekomi erzeugte Links hängen die Empfehlung standardmäßig als ?via= an, und Rekomi liest sowohl via als auch rekomi_ref aus den URL-Parametern des Verkaufs. Kampagnenlinks, die direkt auf deine Gumroad-Produktseiten zeigen, werden also ohne weiteres Zutun zugeordnet.
• Du schickst Käufer von deiner eigenen Marketing-Website zu Gumroad? Installiere dort das Rekomi-Tracking-Skript (die Anleitung für deine Website-Plattform im Installations-Hub deckt es ab) und ergänze deine Kaufen-Links:

// Decorate Gumroad product links with the captured referral
const ref = window.Rekomi?.getReferral?.();
const url = new URL("https://yourname.gumroad.com/l/your-product");
if (ref) url.searchParams.set("rekomi_ref", ref);
// use url.toString() as the href on your Buy button

Verlängerungen tragen nie den Link-Parameter. Die wiederkehrenden Zahlungen für Mitgliedschaften kommen bei Gumroad ohne url_params an, deshalb schreibt Rekomi sie automatisch anhand des ersten zugeordneten Verkaufs des Kunden gut (der Abgleich über die Kundenhistorie, den jede native Verbindung für Verlängerungen nutzt).

Abgleich über die Lead-E-Mail (Fallback). Erreicht ein Verkauf Rekomi ohne rekomi_ref oder via am Produktlink, gleicht Rekomi die E-Mail-Adresse des Käufers aus dem Verkauf 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. Ein Affiliate-Gutschein, der als Gumroad-Angebotscode (Offer Code) eingelöst wird, hat immer Vorrang, wenn er vorhanden ist, danach der Link-Parameter, danach bei Verlängerungen der erste zugeordnete Verkauf des Kunden. Der Lead-Abgleich läuft nur, wenn alle drei nicht greifen, und er überspringt Affiliates, die mit ihrer eigenen E-Mail-Adresse kaufen.

Was erfasst wird

• Verkäufe. Einmalkäufe und die erste Zahlung einer Mitgliedschaft werden als einmalige Conversions erfasst; wiederkehrende Zahlungen für Mitgliedschaften als wiederkehrende Conversions für denselben Affiliate. Gumroad rechnet jede Zahlung in US-Dollar ab, die Beträge sind also immer USD.
• Erstattungen. Eine volle Erstattung holt die Provision automatisch vollständig zurück. Teilerstattungen verringern Provisionen nicht automatisch: Rekomi vermerkt, dass es eine Teilerstattung gab, lässt die Provision aber unverändert, damit du sie bei Bedarf anpassen kannst. Erreicht eine Reihe von Teilerstattungen 100%, wird einmal vollständig zurückgeholt.
• Streitfälle. Eine Rückbuchung holt die Provision zurück wie eine volle Erstattung.
• Lebenszyklus von Mitgliedschaften. Kündigungen, beendete Abonnements und Neustarts werden als Abo-Ereignisse erfasst, damit Berichte, die Kündigungen berücksichtigen, und wiederkehrende Provisionen stimmen (eine neu gestartete Mitgliedschaft wird wieder dem ursprünglichen Affiliate gutgeschrieben).
• Testkäufe. Gumroad kennzeichnet die eigenen Testkäufe eines Verkäufers, und Rekomi erfasst sie bewusst als Verbindungstests, nicht als Provisionen: Ein Testkauf aktualisiert „letztes Ereignis“ auf der Einrichtungsseite, damit du die Strecke von Ende zu Ende prüfen kannst, ohne dass Geld entsteht. Auch Starts einer kostenlosen Testphase (Verkäufe über $0) erzeugen keine Conversion; erst die erste echte Zahlung tut das.

So authentifiziert Rekomi die Benachrichtigungen von Gumroad

Ganz offen: Gumroad signiert seine Webhook-Benachrichtigungen nicht. Es gibt keine Signatur zu prüfen, deshalb authentifiziert Rekomi Zustellungen stattdessen mit mehreren Prüfschichten:

• Deine Benachrichtigungen kommen über eine geheime URL pro Workspace an, die Rekomi bei Gumroad registriert hat. Behandle sie wie ein Passwort: Das Dashboard zeigt sie nur den Ownern des Workspaces, und sie wird bei jedem Neuverbinden rotiert.
• Zustellungen zu Verkäufen, Erstattungen und Streitfällen sind an deine Verkäuferidentität gebunden und werden für jeden anderen Verkäufer abgelehnt. Benachrichtigungen zum Lebenszyklus von Mitgliedschaften enthalten kein Verkäuferfeld, deshalb werden sie nur akzeptiert, wenn sie zu einem Abonnement passen, das Rekomi für dich bereits verfolgt.
• Bei jedem Geldereignis (Verkauf, Erstattung, Streitfall) liest Rekomi den Verkauf mit deinem Token über die API von Gumroad zurück und erfasst die Beträge aus diesem verlässlichen Abruf, nie aus der rohen Benachrichtigung, und gleicht dabei die Kennungen ab. Eine Benachrichtigung, die diesen Abgleich nicht besteht, wird abgelehnt.

Durch diesen Abgleich wird Geld nur erfasst, wenn die API von Gumroad selbst bestätigt, dass der Verkauf existiert und übereinstimmt. Es bedeutet aber auch, dass das Zugriffstoken der Verbindung für das Tracking unverzichtbar ist: Wird es widerrufen, stoppt das Tracking (siehe Verbindungsstatus unten).

Die Zustellung ist lückenhaft: Lücken und nachträglicher Import

Gumroad wiederholt eine fehlgeschlagene Zustellung nur ein paar Mal innerhalb von etwa 14 Minuten, und nur dann, wenn dein Endpunkt mit bestimmten Serverfehlern antwortet. Eine Zustellung, die in ein Timeout läuft oder keine Verbindung bekommt, wird ohne Wiederholung verworfen. Der Handler von Rekomi ist so gebaut, dass er deutlich innerhalb des Zustellfensters von Gumroad antwortet. Sind Rekomi oder die API von Gumroad aber länger nicht erreichbar, als die Wiederholungsstaffel dauert, kann ein Verkauf in diesem Zeitraum fehlen.

Die Teillösung ist der Import der Verkaufshistorie als nachträglicher Import (Backfill): Öffne Einstellungen > Umzug, wähle Gumroad und starte in Schritt 2 den Abruf der Verkäufe, mit Von auf dem Startdatum der Lücke. Das Token deines verbundenen Kontos wird automatisch verwendet, und ein erneuter Lauf ist gefahrlos (bereits erfasste Verkäufe werden als Duplikate übersprungen). Zwei Einschränkungen. Erstens kann der Import Verkäufe nachholen, die über die eingebaute Affiliate-Funktion von Gumroad liefen, aber ein fehlender Verkauf, der über den Empfehlungsparameter im Link zugeordnet wurde, lässt sich aus der API von Gumroad nicht rekonstruieren (die Verkaufs-API von Gumroad gibt keine URL-Parameter heraus). Erfasse diese Conversions manuell anhand der Verkaufsdatensätze in Gumroad. Zweitens überspringt der Import Verkäufe, die im Zeitraum der Lücke erstattet oder zurückgebucht wurden (dieses Geld wurde bei Gumroad schon zurückgeholt). Prüfe diese also manuell, falls Provisionen aus der Lücke rückgängig gemacht werden müssen.

Deine bestehenden Gumroad-Affiliates und die Historie importieren

Du ziehst ein bestehendes Affiliate-Programm von Gumroad um? Der Import hat zwei Schritte:

1. CSV der Affiliate-Liste. Das Dashboard von Gumroad exportiert deine Affiliate-Liste (Exporte mit mehr als 500 Affiliates kommen per E-Mail). Lade sie unter Einstellungen > Umzug hoch. Affiliate-Links von Gumroad mit /a/ lassen sich nicht übernehmen (ihre undurchsichtigen IDs funktionieren nur innerhalb von Gumroad), deshalb bekommen importierte Affiliates neue Rekomi-Links. Der Provisionssatz und die Produktauswahl jedes Affiliates landen in den Importnotizen der jeweiligen Zeile.
2. Verkaufshistorie über die API. Ist die Affiliate-Liste fertig importiert, rufst du die bisherigen Verkäufe jedes Affiliates direkt über die API von Gumroad ab. Die Historie wird als abgeschlossene Datensätze importiert (Gumroad hat seine Affiliates alle zwei Wochen ausgezahlt). Statistiken und die wiederkehrende Attribution werden übernommen, aber nichts wird auszahlbar, und Guthaben werden nie rückwirkend gutgeschrieben.

Die vollständige Anleitung ist Umzug von Gumroad.

Gut zu wissen

• Eine Conversion-Quelle pro Workspace. Gumroad Connect schließt Stripe (über die Rekomi-App für Stripe), Paddle, Braintree, Shopify, Lemon Squeezy, Chargebee, Polar, Recurly, 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.
• Die Marketplace-Affiliates von Gumroad funktionieren weiter. Gumroad hat eine eingebaute Affiliate-Funktion, und das Verbinden mit Rekomi lässt sie unberührt. Du kannst beide parallel betreiben oder die eingebaute auslaufen lassen. Rekomi bringt plattformübergreifende Affiliate-Konten, Freigaben und Betrugsschutz und ein echtes Auszahlungssystem obendrauf.
• Zugriffstoken laufen nicht ab, aber ein Widerruf passiert lautlos. Widerrufst du die Rekomi-App in Gumroad, ist das Token ungültig UND die Benachrichtigungen hören stillschweigend auf. Der Gesundheitscheck von Rekomi prüft die Verbindung regelmäßig und markiert sie in diesem Fall als unterbrochen (mit einer E-Mail zum Neuverbinden); zusätzlich zeigt das Dashboard ein dauerhaftes Banner zum Neuverbinden.
• Trennen räumt auch bei Gumroad auf. Beim Trennen werden die sechs Ressourcen-Abonnements in deinem Gumroad-Konto gelöscht und das gespeicherte Token entfernt. Neu verbinden erzeugt neue Zugangsdaten; die alte Webhook-Adresse funktioniert dann nicht mehr.

Die Installation testen

Tätige einen Testkauf eines deiner Produkte mit ?rekomi_ref=test am Link (oder nutze als Verkäufer den Testkauf-Ablauf von Gumroad). Die Zustellung erscheint innerhalb einer Minute als „letztes Ereignis“ unter /dashboard/setup/gumroad; Testkäufe des Verkäufers prüfen die Strecke, ohne eine Provision zu erzeugen. Lass dann einen echten Kauf über den Link eines freigegebenen Affiliates laufen und prüfe die Conversion im Tab Performance der Kampagne.

Fehlerbehebung

Banner oder E-Mail „Deine Gumroad-Verbindung ist unterbrochen.“ Der Zugriff der Rekomi-App wurde in Gumroad widerrufen (was auch die Benachrichtigungen stillschweigend stoppt), oder die Registrierung für Verkaufsbenachrichtigungen ist verschwunden. Klicke erneut auf Gumroad verbinden; beim Neuverbinden werden alle sechs Feeds neu registriert und die Zugangsdaten rotiert. Die Tracking-Historie bleibt erhalten.

Verkäufe kommen an, aber kein Affiliate erhält eine Gutschrift. Der Verkauf hat Rekomi erreicht, aber ohne Empfehlung. Prüfe, ob der Link, den der Käufer genutzt hat, wirklich ?rekomi_ref=SLUG oder ?via=SLUG an der Gumroad-Produkt-URL trug, ob der Slug zu einem freigegebenen Affiliate gehört und (bei Links von deiner eigenen Website) ob das Tracking-Skript lief, bevor der Käufer weitergeklickt hat. Verlängerungen werden anhand des ersten zugeordneten Verkaufs des Kunden gutgeschrieben, ein nicht zugeordneter erster Verkauf bedeutet also auch nicht zugeordnete Verlängerungen.

Ein Verkauf fehlt komplett. Prüfe auf der Einrichtungsseite, ob die Gumroad-Verbindung in Ordnung ist, und starte dann den nachträglichen Abruf (Einstellungen > Umzug > Gumroad > Schritt 2) für den betroffenen Zeitraum. Gumroad verwirft Zustellungen mit Timeout ohne Wiederholung, längere Ausfallzeiten brauchen also den nachträglichen Import. Der Abruf holt nur Verkäufe zurück, die über die eingebaute Affiliate-Funktion von Gumroad liefen; einen fehlenden Verkauf, der über den Link zugeordnet war, musst du manuell anhand der Verkaufsdatensätze in Gumroad erfassen.

Alter Weg: Relay über die Ping URL (S2S)

Vor der nativen Verbindung lief das Gumroad-Tracking über ein selbst gehostetes Relay: Die Ping URL von Gumroad sendet jeden Verkauf per POST an einen Handler, den du betreibst, und dein Handler leitet ihn mit einer HMAC-Signatur an den S2S-Endpunkt von Rekomi weiter. Die Anleitung bleibt hier für Verkäufer, die Gumroad nicht nativ verbunden haben. Kannst du den Button „Verbinden“ nutzen, nimm ihn (keine eigene Infrastruktur, dafür Erstattungen, Streitfälle und den Lebenszyklus von Mitgliedschaften inklusive).

Öffne in Gumroad Settings > Advanced > Ping URL und lass sie auf einen Handler in deinem Backend zeigen. Gumroad signiert Pings nicht, schütze die eingehende Strecke also mit einem gemeinsamen Secret in der URL (und/oder einer IP-Allowlist). Der API-Schlüssel und das HMAC unten schützen den Aufruf deines Relays bei Rekomi, nicht den Aufruf von Gumroad bei dir. Dieses alte Relay liest den Parameter ?via=; die native Verbindung liest sowohl via als auch rekomi_ref.

// Node example with express
const express = require('express');
const crypto = require('crypto');

// Every call to Rekomi carries your API key (rk_live_...) as a Bearer token plus a
// timestamped HMAC signature: X-Rekomi-Signature: t=<unix>,sig=<hex>, where <hex> is
// HMAC-SHA256 of `${ts}.${rawBody}` with your signing secret. Full contract:
// /docs/developers/s2s-tracking
function rekomiHeaders(body) {
  const ts = Math.floor(Date.now() / 1000);
  const sig = crypto.createHmac('sha256', process.env.REKOMI_SIGNING_SECRET)
    .update(`${ts}.${body}`).digest('hex');
  return {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.REKOMI_API_KEY}`,
    'X-Rekomi-Signature': `t=${ts},sig=${sig}`,
  };
}

app.post('/webhooks/gumroad', express.urlencoded({ extended: true }), async (req, res) => {
  // 1. Verify shared secret (or IP allowlist at the edge).
  if (req.query.secret !== process.env.GUMROAD_SHARED_SECRET) {
    return res.sendStatus(401);
  }

  const sale = req.body;

  // 2. Pull the affiliate slug from url_params[via]. Gumroad nests the original URL query
  //    under url_params; extended: true makes urlencoded parse the nested keys.
  const referral = sale.url_params?.via || sale.url_params?.rekomi_ref || sale.url_params?.ref;
  if (!referral) return res.sendStatus(200); // No affiliate involved.

  // 3. Refunds: the ping fires again with refunded=true. Reverse instead of recording.
  if (sale.refunded === 'true' || sale.refunded === true) {
    const refundBody = JSON.stringify({
      externalEventId: sale.sale_id, // Same id as the original sale
    });
    await fetch('https://api.rekomi.com/api/tracking/refund', {
      method: 'POST',
      headers: rekomiHeaders(refundBody),
      body: refundBody,
    });
    return res.sendStatus(200);
  }

  // 4. Relay the sale to Rekomi. Gumroad already sends price in cents (integer),
  //    so do NOT multiply by 100.
  const body = JSON.stringify({
    externalEventId: sale.sale_id,
    affiliateSlug: referral,
    amountCents: parseInt(sale.price, 10),
    currency: 'USD', // Gumroad settles every charge in USD
    customerEmail: sale.email,
  });

  await fetch('https://api.rekomi.com/api/tracking/s2s', {
    method: 'POST',
    headers: rekomiHeaders(body),
    body,
  });
  res.sendStatus(200);
});

Besonderheiten des Relays, abgeglichen mit dem aktuellen Verhalten von Gumroad:

• Gumroad sendet price bereits in Cent (Integer). Multiplizierst du mit 100, erhältst du eine 100-fach zu hohe Provision, der mit Abstand häufigste Fehler bei dieser Installation. Das Feld currency im Ping ist die Währungsangabe für die Preisanzeige des Produkts, nicht die Abrechnungswährung; das Geld ist immer in US-Cent.
• Formularkodierter Body mit verschachtelten Schlüsseln. Gumroad sendet per POST application/x-www-form-urlencoded, kein JSON. Nutze einen Parser, der verschachtelte Schlüssel kann, damit url_params[via] aufgelöst wird.
• Wiederholungen sind wenige und eng begrenzt. Gumroad stellt bis zu 3-mal erneut zu (4 Versuche insgesamt) innerhalb von etwa 14 Minuten, und nur dann, wenn dein Handler mit 499, 500, 502, 503 oder 504 antwortet. Alles andere, was schiefgeht, einschließlich eines Timeouts im Handler oder einer fehlgeschlagenen Verbindung, wird ohne Wiederholung verworfen. Mach das Relay wiederholungssicher (externalEventId dedupliziert auf Seiten von Rekomi), halte es schnell und betreibe es auf einer Infrastruktur mit hoher Verfügbarkeit. Eine Warteschlange mit eigenen Wiederholungen auf deiner Seite ist das robuste Muster.
• Die Ping URL löst bei jedem Verkauf aus, auch bei solchen ohne Affiliate. Antworte bei diesen früh mit 200, damit die Zustellung als erledigt gilt.
• Affiliate-Links müssen den Parameter ausdrücklich tragen. Gumroad hat keine Cookie-Ebene, die Rekomi steuert; der Slug muss in der URL stehen, auf der der Käufer landet.

Verwandte Seiten

• Umzug von Gumroad
• Referenz der S2S-Tracking-API
• Umgang mit Erstattungen