Auf Shopify installieren

Die App Rekomi Affiliate Marketing ist im Shopify App Store verfügbar. Die Installation ist der empfohlene Weg: Sie kommt ohne Programmierung aus und erfasst alles, was der manuelle Weg weiter unten erfasst, und noch mehr. Affiliate-Links werden ohne weitere Einrichtung erfasst (die App installiert ihr Web Pixel automatisch und liest zusätzlich den Kaufverlauf, den Shopify selbst zu jeder Bestellung speichert, sodass die Attribution über Links auch dann funktioniert, wenn der Käufer Tracker blockiert). Bestellungen werden über den Bestell-Webhook der App automatisch zugeordnet, Erstattungen holen die Provision zurück, und jeder Affiliate kann einen eigenen Shopify-Rabattcode bekommen, ohne Änderungen am Theme und ohne ein Relay, das du bauen müsstest.

Die Rekomi-App installieren (empfohlen)

Schritt 1: aus dem App Store installieren. Öffne Rekomi Affiliate Marketing im Shopify App Store und klicke auf Install. Bestätige die angefragten Berechtigungen: Bestellungen lesen, Produkte lesen, Kunden lesen, Rabatte schreiben (nur genutzt, um Rabattcodes für Affiliates anzulegen), das Berechtigungspaar für das Web Pixel und Store Credit schreiben (nur genutzt, wenn eine Kampagne Affiliates mit Shop-Guthaben belohnt). Damit kann Rekomi Conversions erfassen, Provisionen bei Erstattungen zurückholen und Shop-Guthaben gutschreiben.

Schritt 2: einen Plan wählen. Die App öffnet sich auf ihrer Seite Abonnement. Wähle einen Plan und bestätige die Belastung auf dem Abrechnungsbildschirm von Shopify. Jeder Plan beginnt mit einer 14-tägigen kostenlosen Testphase, und dein Abonnement wird zusammen mit deinen anderen Apps über Shopify abgerechnet.

Du hast schon ein Rekomi-Konto? Hast du dich zuerst auf rekomi.com registriert, erkennt die App die E-Mail-Adresse, mit der du installiert hast, und fragt, ob du diesen Shop mit dem Workspace verknüpfen willst, für den du schon bezahlst, oder ob du ihn als eigenen Workspace einrichten willst. Beim Verknüpfen geht ein sechsstelliger Code an diese E-Mail-Adresse; sobald du ihn bestätigst, ziehen der Shop, seine Produkte und sein Tracking in deinen bestehenden Workspace um, und dein Plan bleibt genau so, wie er ist, mit der Abrechnung dort, wo sie war. Hast du mit einer anderen E-Mail-Adresse installiert, wähle stattdessen die Option zum Anmelden und such den Workspace auf rekomi.com aus. Du kannst auch im Web starten: Öffne in deinem Rekomi-Dashboard die Einrichtung, wähle Shopify und klicke vor der Installation auf Shop verbinden. Die Installation wird dann ohne Rückfragen verknüpft.

Schritt 3: deine Kampagne erstellen. Die Einrichtungsanleitung führt dich durch das Erstellen einer Kampagne mit der Provision, die du zahlen willst, und durch das Verknüpfen deines Shops mit ihr. Rekomi wartet ab sofort auf Bestellungen. Im Kampagnenformular der App legst du die Provision pro Verkauf fest, als Prozentsatz oder festen Betrag. Pay-per-Lead und Pay-per-Click stellst du im vollständigen Dashboard unter app.rekomi.com ein.

Schritt 4: prüfen. Gib eine Testbestellung auf, bei der ?via=test an eine URL deines Storefronts angehängt ist, und prüfe, ob die Conversion innerhalb einer Minute im Tab Performance der Kampagne erscheint.

Ab dann läuft das ganze Programm über die Rekomi-App im Shopify admin: Kampagnen und der Designer für die Anmeldeseite, der Produktkatalog mit Sätzen pro Produkt, Gutscheinangebote, die du mit der Produktauswahl von Shopify selbst eingrenzt, Affiliates und ihre Produktlinks, vermittelte Verkäufe mit direktem Link zur Bestellung in deinem Admin, Banner-Uploads für Werbematerial, Einladungen per Klick für deine besten Kunden, der Import aus 21 Quellen unter Einstellungen > Import, Auszahlungen (per Klick oder nach einem automatischen Zeitplan) und die Abrechnung deines Plans.

Was die App für deinen Shop erledigt

Empfehlungslinks. Jeder Affiliate bekommt einen Link zu deinem Shop mit seinem Code (und Produktlinks aus deinem synchronisierten Katalog). Das Web Pixel der App erfasst den Klick First-Party, und Rekomi liest zusätzlich den Kaufverlauf, den Shopify zu jeder Bestellung speichert. So wird ein Verkauf auch dann zugeordnet, wenn der Käufer Tracker blockiert hat oder erst Tage später zurückkommt.

Rabattcodes. Jeder Affiliate kann einen persönlichen Code bekommen, der als echter Shopify-Rabatt aus einem von dir festgelegten Gutscheinangebot angelegt wird (Prozent- oder Betragsrabatt, optional mit der Produktauswahl von Shopify auf bestimmte Produkte beschränkt). Ein eingelöster Code schreibt dem Affiliate auch ohne erfassten Klick gut, und so konvertiert der meiste Traffic aus Social Media und Videos. Widerrufst du den Code, wird der Shopify-Rabatt deaktiviert.

Bestellungen. Der Webhook orders/paid von Shopify ist der Verkauf: Die Provision entsteht in dem Moment, in dem die Bestellung bezahlt ist, standardmäßig auf die Bestellsumme oder auf die Warenzeile, wenn ein Satz pro Produkt gilt. Testbestellungen werden nur erfasst, solange dein Workspace im Testmodus ist.

Sätze pro Produkt und zugewiesene Partner. Lege für Produkte, die du pushen willst, einen anderen Satz fest (oder null für die, bei denen du das nicht willst), und weise ein Produkt bestimmten Affiliates zu, damit nur sie daran verdienen. Siehe Provisionen pro Produkt.

Aus Kunden werden Affiliates. Die Seite Kunden einladen listet deine besten Kunden nach ihrem Gesamtumsatz; lade sie per Klick ein, und sie bekommen einen Link und einen Code.

Shop-Guthaben statt Geld. Eine Kampagne kann Affiliates statt mit einer Geldprovision mit Shop-Guthaben in Shopify belohnen: Der Provisionssatz, den du festlegst (oder ein fester Betrag pro Verkauf), wird dem Affiliate als Shop-Guthaben auf seinem Shopify-Kundenkonto gutgeschrieben und bei seinem nächsten Checkout verrechnet. Niemand braucht eine Auszahlungsmethode oder ein Steuerformular, und eine Erstattung nimmt das Guthaben zurück. Für Shop-Guthaben braucht die App die Berechtigung, Store Credit zu schreiben. Hat dein Shop die App installiert, bevor es diese Berechtigung gab, öffne die Rekomi-App einmal und bestätige die aktualisierten Berechtigungen, wenn Shopify danach fragt. Siehe Shop-Guthaben als Belohnung.

Auszahlungen und Steuern. Für Geldprovisionen finanzierst du einen Auszahlungslauf (oder schaltest automatische Auszahlungen ein), und Rekomi bezahlt jeden Affiliate in 130+ Ländern, berechnet pauschal 3% der ausgezahlten Provisionen über deine Shopify-Rechnung, holt die Formulare W-9 und W-8 ein und reicht als zahlende und meldende Stelle (Payer of Record) die 1099-NECs ein. Siehe Auszahlungen.

Erstattungen, Stornierungen und Rückbuchungen

• Erstattungen. Shopify löst bei jeder Erstattung refunds/create aus, und die App hört darauf: Eine Teilerstattung holt ihren anteiligen Teil der Provision zurück (vor Steuern), eine volle Erstattung holt alles zurück und setzt den Verkauf auf Erstattet. Du musst nichts weiterleiten.
• Eine Erstattung, nachdem der Affiliate bezahlt wurde. Der erstattete Anteil der ausgezahlten Provision wird automatisch von der nächsten Auszahlung dieses Affiliates abgezogen und erscheint auf deiner Seite Auszahlungen unter „Rückforderungen aus Rückerstattungen“, wo du ihn auch abschreiben kannst. Willst du das Geld sofort zurück, kannst du die bezahlte Position weiterhin auf der Seite der Auszahlung über Stripe zurückbuchen. Siehe Erstattungen nach einer Auszahlung.
• Stornierungen. Eine Bestellung, die vor der Zahlung storniert wird, wird nie zum Verkauf; eine bezahlte Bestellung, die du stornierst, erstattet Shopify, und diese Erstattung holt die Provision zurück.
• Rückbuchungen. Ein verlorener Streitfall bei Shopify Payments ist kein Erstattungsereignis. Erstatte die Bestellung in Shopify (damit refunds/create ausgelöst wird) oder erkläre den Verkauf auf der Seite Conversions für ungültig.
• Änderungen an Bestellungen. Fügst du einer bezahlten Bestellung Artikel hinzu, ändert das die schon erfasste Provision nicht; das Entfernen von Artikeln ist in Shopify eine Erstattung und holt ihren Anteil zurück.
• Die Wartefrist für Erstattungen. Provisionen werden erst nach deiner Erstattungsfrist auszahlbar (standardmäßig 30 Tage), die meisten Erstattungen kommen also an, bevor Geld fließt.

Shopify Collabs

Shopify hat ein eigenes Affiliate-Programm namens Collabs. Rekomi ergänzt plattformübergreifende Affiliate-Identitäten (ein Affiliate arbeitet für viele Marken), Provisionsstufen, Sätze pro Produkt, Sub-Affiliate-Recruiting, Shop-Guthaben als Belohnung und das offene Creator-Netzwerk. Beides kann im selben Shop nebeneinander laufen, und der Import unter Einstellungen > Import übernimmt deine Collabs-Affiliates samt Verlauf.

Weg für Entwickler: Custom Pixel plus Webhook an S2S

Der Rest dieser Seite ist für Shops, die lieber keine App installieren. Alles oben passiert mit der App von selbst; der manuelle Weg erfasst nur Links und Bestellungen.

Willst du die App nicht installieren, besteht der manuelle Weg zum Selbermachen aus einem Custom Pixel für die Klickerfassung plus einem Bestell-Webhook, der an den S2S-Endpunkt von Rekomi weitergeleitet wird. Zwei Eigenheiten der Shopify-Architektur bestimmen diesen Weg. Erstens: Shopify Payments ist intern Stripe, aber das Stripe-Konto gehört Shopify, nicht dir, du hast also keinen eigenen Stripe-Webhook, den Rekomi abonnieren könnte. Zweitens: Custom Pixels laufen in einer abgeschotteten Laufzeitumgebung (Sandbox), in der externe <script>-Tags nicht laden können, deshalb funktioniert auch der übliche Ansatz „Füge dieses Skript in deinen Head ein“ nicht. Die Installation hat deshalb zwei Hälften: Ein Custom Pixel erfasst den Affiliate-Klick (Teil 1), und ein Bestell-Webhook, der an den S2S-Endpunkt von Rekomi weitergeleitet wird, erfasst die Conversion serverseitig (Teil 2). Installiere beide.

Teil 1: Custom Pixel (Klickerfassung)

Schritt 1. Im Shopify admin: Settings > Customer events > Add custom pixel.

Schritt 2. Nenne es Rekomi. Setze Permission auf Not required. Füge den Code des Custom Pixels ein (das vollständige Snippet findest du in deinem Rekomi-Dashboard unter Einrichtung, Tracking-Skript installieren, wenn du Shopify wählst).

Schritt 3. Klicke auf Save und dann auf Connect.

Das Custom Pixel läuft im gesamten Storefront und im Checkout. Es kümmert sich nur um die Klickerfassung:

• page_viewed: liest ?via= aus der Landing-URL, sendet den Klick (den Slug des Affiliates plus deine Programm-ID) per POST an /api/v1/r/c und merkt sich den Slug, damit er bis zur Bestellung mitreist.

Das Custom Pixel erfasst den Verkauf nicht. Es gibt keinen Conversion-Aufruf im Browser: Der alte Verkaufsweg über convert() im Browser-Pixel wurde entfernt, und die Conversion wird in Teil 2 serverseitig erfasst, wo der Bestell-Webhook von Shopify die vollständigen Bestelldaten ohne die Einschränkungen der Sandbox liefert.

Teil 2: Bestell-Webhook an S2S (Conversion senden)

Hier wird die Conversion erfasst. Richte ein serverseitiges Relay für den Order-Webhook von Shopify ein.

Schritt 1. Shopify admin > Settings > Notifications > Webhooks > Create webhook.

• Event: Order payment
• URL: https://your-app.example.com/rekomi-shopify-webhook?secret=YOUR_SHARED_SECRET
• Format: JSON
• API version: die neueste stabile

Schritt 2. Baue den Handler für das Relay. Shopify signiert jeden Webhook mit dem Secret, das du beim Anlegen des Webhooks festlegst (HMAC-SHA256 im Header X-Shopify-Hmac-Sha256). Prüfe die Signatur und leite dann mit HMAC an den S2S-Endpunkt von Rekomi weiter. total_price von Shopify ist ein Dezimalwert in der Heimatwährungseinheit der Shop-Währung (order.currency), deshalb rechnet der Handler ihn vor dem Senden in ganzzahlige kleinste Einheiten dieser Währung um: ganze Yen bei JPY, Tausendstel bei KWD, Cent bei allen anderen (siehe Conversion-Währung).

const crypto = require('crypto');

app.post('/rekomi-shopify-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  // 1. Validate Shopify HMAC
  const shopifyHmac = req.get('X-Shopify-Hmac-Sha256');
  const computed = crypto
    .createHmac('sha256', process.env.SHOPIFY_WEBHOOK_SECRET)
    .update(req.body)
    .digest('base64');
  if (computed !== shopifyHmac) return res.sendStatus(401);

  // 2. Validate URL shared secret too (defense in depth)
  if (req.query.secret !== process.env.SHARED_SECRET) return res.sendStatus(401);

  const order = JSON.parse(req.body.toString());

  // 3. Pull the affiliate slug from note_attributes (set by your storefront snippet).
  //    The attribute name is rekomi_via, the same name the Rekomi pixel snippet uses.
  const noteAttrs = order.note_attributes || [];
  const referralAttr = noteAttrs.find(a => a.name === 'rekomi_via');
  if (!referralAttr) return res.sendStatus(200); // No affiliate involved.

  // 4. Relay to Rekomi. Field names are camelCase; the signature is
  //    t={unix},sig={hex} where hex = HMAC-SHA256 of `${ts}.${body}`.
  //    total_price is a major-unit decimal in the shop currency; Rekomi wants integer
  //    minor units of order.currency (whole yen for JPY, thousandths for KWD).
  const ZERO_DEC = new Set(['BIF', 'CLP', 'DJF', 'GNF', 'ISK', 'JPY', 'KMF', 'KRW', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF']);
  const THREE_DEC = new Set(['BHD', 'JOD', 'KWD', 'OMR', 'TND']);
  const dec = ZERO_DEC.has(order.currency) ? 0 : THREE_DEC.has(order.currency) ? 3 : 2;
  const ts = Math.floor(Date.now() / 1000);
  const body = JSON.stringify({
    externalEventId: order.id.toString(),
    affiliateSlug: referralAttr.value,
    amountCents: Math.round(parseFloat(order.total_price) * 10 ** dec), // integer minor units of order.currency
    currency: order.currency,
    customerEmail: order.email,
  });
  const sig = crypto
    .createHmac('sha256', process.env.REKOMI_SIGNING_SECRET)
    .update(`${ts}.${body}`)
    .digest('hex');
  await fetch('https://api.rekomi.com/api/tracking/s2s', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.REKOMI_API_KEY}`,
      'X-Rekomi-Signature': `t=${ts},sig=${sig}`,
    },
    body,
  });
  res.sendStatus(200);
});

In das Array note_attributes sollte der Storefront beim Anlegen der Bestellung den Slug des Affiliates schreiben, unter dem Attributnamen rekomi_via (demselben Namen, den das Rekomi-Pixel-Snippet nutzt). Die Pixel-Sandbox kann window.Rekomi nicht bereitstellen, deshalb läuft diese Hälfte stattdessen in deinem Theme: Füge das normale Rekomi-Tracking-Skript in den Head deines Themes ein (Theme-Code kann im Gegensatz zu Pixels externe Skripte laden) und dann ein Storefront-Snippet (Theme > Edit code > sections/header.liquid oder ähnlich), das über attributes der Cart API window.Rekomi.getReferral() vor dem Checkout als rekomi_via in die Bestellung schreibt.

Die Installation testen

Gib eine echte Bestellung auf, bei der ?via=test an eine URL deines Storefronts angehängt ist. Die Conversion sollte innerhalb einer Minute im Tab Performance der Kampagne erscheinen. Wird nur ein Klick registriert (keine Conversion), hat Teil 1 den Klick erfasst, aber Teil 2 hat den Verkauf nicht erfasst: Entweder wurde der Slug des Affiliates nicht in die note_attributes der Bestellung geschrieben, oder der Bestell-Webhook hat dein Relay nicht erreicht. Prüfe die Logs deines Relays und ob der Storefront den Slug in die Warenkorb-Attribute geschrieben hat. Shopify löst den Bestell-Webhook auch für Testbestellungen aus; willst du keine Testdaten erfassen, überspringe in deinem Relay Bestellungen mit test: true.

Gut zu wissen (manueller Weg)

Custom Pixels laufen in einer Sandbox. Externe <script>-Tags können in einem Custom Pixel nicht laden; alles muss inline stehen. Deshalb enthält Teil 1 den Code für die Klickerfassung direkt, statt das normale Head-Skript zu laden.

Shopify Payments ist nicht dein Stripe-Konto. Auch wenn Shopify Zahlungen intern über Stripe abwickelt, kannst du Rekomi nicht für die Stripe-Webhooks von Shopify anmelden. Custom Pixel und S2S-Webhook sind die beiden unterstützten Wege, Conversions auf Shopify zuzuordnen.

Der Bestell-Webhook enthält die vollständigen Bestelldaten. Der Conversion-Aufruf liest total_price, currency, email und den Slug des Affiliates direkt aus dem Bestell-JSON, das Shopify an dein Relay liefert, ohne Einschränkungen durch die Sandbox und ohne etwas aus der gerenderten Seite herauslesen zu müssen.

Erstattungen (manueller Weg)

Shopify löst bei jeder Erstattung den Webhook refunds/create aus. Abonniere ihn und leite ihn an den Endpunkt /api/tracking/refund von Rekomi weiter, mit derselben externalEventId, die du für die ursprüngliche Bestellung gesendet hast. Die Provision wird automatisch zurückgeholt. (Mit installierter App brauchst du dafür kein Relay: Die App abonniert den Erstattungs-Webhook selbst.)

Fehlerbehebung (manueller Weg)

Das Custom Pixel ist gespeichert, aber in Rekomi erscheinen keine Klicks. Prüfe, ob das Custom Pixel auf Connected gesetzt ist (nicht nur gespeichert). Schau im Bereich Customer events nach dem Status-Badge des Pixels.

Die Conversion wird doppelt gesendet. Dein Relay für den Bestell-Webhook hat dieselbe Bestellung mehr als einmal an den S2S-Endpunkt geliefert (Shopify wiederholt bei Antworten außerhalb von 2xx). Rekomi entfernt Duplikate anhand der externalEventId, der zweite Aufruf bewirkt also stillschweigend nichts. Das ist kein Fehler.

Der Slug des Affiliates fehlt in note_attributes. Dein Storefront-Snippet hat den Slug vor dem Checkout nicht in die Warenkorb-Attribute geschrieben. Prüfe, ob der Storefront das Snippet enthält, und teste dann mit geöffneten DevTools im Browser, ob der Aufruf für das Attribut an die Cart API ausgelöst wird.

Verwandte Seiten

• Rekomi für Online-Shops
• Shop-Guthaben als Belohnung
• Auszahlungen
• Referenz der S2S-Tracking-API
• Checkout-Tracking ohne Code und ohne Stripe
• Dokumentation zu Custom Pixels von Shopify