Was den Shop verlässt

Diese Frage zuerst, weil sie über den Rest entscheidet. Der Conversion-Aufruf braucht drei Angaben: Ihre Bestellnummer, den Betrag, auf den Provision gerechnet wird, und die Währung. Dazu muss erkennbar sein, welcher Partner gemeint ist.

Alles Weitere ist freiwillig. Sie können eine Transaktionsnummer, eine Kundenadresse, einen Produktnamen, eine Klick-ID oder eine Notiz mitgeben; für die Provisionsberechnung braucht Afflixo nichts davon. Wer keine Kundendaten übergeben will, lässt die Felder einfach weg, und es funktioniert unverändert.

Der Aufruf

Wenn eine Bestellung abgeschlossen ist und Sie wissen, dass sie über einen Partner kam:

POST /api/<merchantSlug>/track/conversion
Content-Type: application/json

{
  "orderId": "ORD-12345",
  "amount": 99.00,
  "currency": "USD",
  "affiliateCode": "ABC123"
}

Der merchantSlug in der URL weist Sie aus, einen API-Key gibt es nicht. Setzen Sie in den Einstellungen ein Webhook-Secret, prüft der Endpunkt zusätzlich eine HMAC-SHA256-Signatur über den Rohkörper der Anfrage.

Ein Hinweis zur Währung: das Feld wird gespeichert und in Benachrichtigungen angezeigt, geht aber nicht in die Rechnung ein. Die Provision wird direkt auf der Zahl berechnet, die Sie in amount senden, ohne Umrechnung. Da Afflixo in US-Dollar abrechnet, rechnen Sie Euro-Beträge um, bevor Sie sie senden, sonst steht ein Euro-Betrag als Dollar in Ihrer Abrechnung.

Doppelte Conversions, der teure Fehler

Zahlungs-Webhooks wiederholen sich. Ein Timeout beim Payment-Provider wiederholt sich. Ihre eigene Retry-Logik wiederholt sich. Erzeugt jede Wiederholung eine neue Conversion, zahlen Sie für eine Bestellung zweimal Provision, und auffallen wird das erst beim Abgleich am Monatsende.

Afflixo entdoppelt auf Ihrer orderId innerhalb Ihres Programms. Dieselbe orderId erneut zu senden gibt die bestehende Conversion samt Provision zurück, statt eine zweite anzulegen. Wiederholen ist damit unbedenklich, ganz ohne Zusatz-Header.

Eine Bedingung: die orderId muss in Ihrem eigenen System eindeutig sein. Ihre Bestellnummer ist normalerweise genau das. Vergibt Ihr Shop Nummern nach Storno oder Neuanlage erneut, klären Sie das zuerst, sonst hält die Entdopplung zwei verschiedene Bestellungen für dieselbe.

Zuordnung, der leise Fehler

Der Partnercode wird in dieser Reihenfolge gesucht: affiliateCode im Body, dann der Header x-affiliate-code, dann das Cookie affiliate_ref, das der Partnerlink gesetzt hat. Fehlt alles drei, wird die Anfrage mit 400 abgelehnt, weil niemand gutgeschrieben werden könnte. Das ist Absicht: lieber ein Fehler als eine stille Fehlzuordnung.

In der Praxis bricht der dritte Weg am häufigsten. Der Besucher klickt den Link am Handy und kauft später am Rechner; das Cookie liegt auf dem anderen Gerät. Oder Ihr Checkout läuft auf einer anderen Domain, und das Cookie kommt dort nicht an. Der zuverlässige Weg ist deshalb: den Code beim Eintreffen aus dem URL-Parameter lesen, in Ihrer eigenen Session oder am Bestelldatensatz ablegen und beim Abschluss ausdrücklich im Body mitsenden.

Provisionsregeln

Drei Einstellungen decken fast jedes Programm: prozentual, fester Betrag, und ein eigener Satz auf einem einzelnen Partner. Sie setzen einen Standard für das Programm und überschreiben ihn, wo nötig; wo beides existiert, gilt der Satz am Partner. Davon getrennt steht der Geltungsbereich: nur die erste Bestellung, die ersten N Bestellungen, oder ein Zeitfenster.

Auszahlung

Der Partner beantragt, Sie geben frei, Sie zahlen auf Ihrem gewohnten Weg. Afflixo hält nur den Status fest, damit nichts zweimal freigegeben wird, und bewegt selbst kein Geld. Diese Grenze ist gewollt.

Mehrstufige Provisionen, eine eigene Domain je Händler, automatische Auszahlung über PayPal oder Stripe und andere Abrechnungswährungen als US-Dollar gibt es nicht. Die vollständige Spezifikation steht in der Entwicklerdokumentation.