PPartnerDesk

12 — MLM-Struktur & Downline

Aktualisiert am 1. Juni 2026

12 — MLM-Struktur & Downline

PartnerDesk unterstützt klassisches Multi-Level-Marketing: ein Partner kann andere Partner werben (= seine Downline). Bei einer Conversion in der Downline bekommt nicht nur der direkte Partner Provision, sondern auch die übergeordneten Sponsoren.

Grundprinzipien

  • Jeder Partner hat genau einen Sponsor (= sein „Referrer"). Der Sponsor ist wiederum ein Partner.
  • Eine Kette nach oben: Direkt-Partner → Sponsor → Sponsor-Sponsor → … bis maximal 10 Ebenen oder bis kein Sponsor mehr existiert.
  • Cycle-Detection verhindert Loops (z. B. wenn A B sponsert und B versehentlich A zugewiesen wird).

Wie wird ein Sponsor zugewiesen?

Drei Wege:

1. Beim Anlegen durch Admin

Admin → „Partner" → „Neu" → Sponsor-Auswahl (Dropdown der vorhandenen Partner).

2. Bei Self-Registration mit ?ref=

Wenn ein Partner sich über <slug>.partnerdesk.io/register?ref=<sponsor-partner-id> anmeldet, wird der Sponsor automatisch zugeordnet.

3. Nach Anlage manuell ändern

Admin → Partner-Detail → Sponsor-Feld editieren. Nur möglich, wenn dadurch kein Cycle entsteht.

4. Automatisch über Cross-Tenant-Recruiting

Wenn Partner A den Partner B über den Marktplatz geworben hat und B sich bei Ihrem Programm bewirbt, bekommt A eine 24-Stunden-Bestätigungsmail. Sobald A bestätigt (oder bereits Partner bei Ihnen ist), wird A automatisch als Sponsor von B eingetragen.

Damit ist der Recruiting-Bonus identisch mit der MLM-Stufe: A verdient an B’s Sales genau das, was Sie in der Kampagne als Level-2-Provision (bzw. Level-3 für A’s eigenen Sponsor usw.) eingestellt haben. Es gibt keinen separaten Bonus-Topf — die normale Downline-Vergütung greift.

Voraussetzung: Ihre Kampagne muss mindestens 2 Provisions-Levels haben, sonst erhält der Werber nichts. Die Verdrahtung überschreibt niemals einen bereits gesetzten Sponsor und ist Cycle-geschützt.

Provisionsverteilung im MLM

Beispiel: Kampagne hat 3 Levels, Provisionen 20 % / 5 % / 2 %.

[Sale 100 € netto bei Partner D]
  ├─ Level 1: Partner D bekommt 20 € (20 %)
  ├─ Level 2: Partner C (D's Sponsor) bekommt 5 € (5 %)
  └─ Level 3: Partner B (C's Sponsor) bekommt 2 € (2 %)

Partner A (B's Sponsor) bekommt nichts, weil die Kampagne nur 3 Levels hat.

Jede dieser drei Provisionen wird als separate Transaction in der DB gespeichert. Damit erscheint sie in den jeweiligen Partner-Listen und wird Teil ihres nächsten Payouts.

Cycle-Detection

Der Algorithmus speichert während der Iteration alle besuchten Partner-IDs. Tritt eine ID zum zweiten Mal auf:

  1. Fehler wird ins Log geschrieben (MLM cycle detected).
  2. Iteration bricht sofort ab.
  3. Bereits berechnete Provisionen oberhalb des Loops bleiben gültig.

Damit ist die Provisionsberechnung selbst bei (unwahrscheinlicher) Datenkorruption sicher.

Inaktive Sponsoren

Wenn ein Sponsor auf einem Level den Status suspended, terminated oder anonymized hat, wird er übersprungen — die nächsthöhere Ebene bekommt die Provision nicht.

Beispiel: D → C (suspended) → B (active).

  • Level 1: D bekommt 20 %.
  • Level 2: leer (C ist suspended).
  • Level 3: B bekommt 2 % als regulärer Level-3-Empfänger.

Damit verlieren Suspended/Terminated-Partner ihre Downline-Provisionen, ohne die Struktur zu verändern.

Maximale Tiefe

  • Campaign.commissionLevels legt die Kampagnen-Tiefe fest (z. B. 3).
  • MAX_MLM_DEPTH = 10 ist die harte System-Obergrenze.

Beides wird bei der Berechnung geprüft. commissionLevels über 10 zu setzen ist möglich, hat aber keine Wirkung über 10 hinaus.

Downline einsehen

Partner-Portal

Partner sieht unter „Downline":

  • Direkte Downline (Level 1).
  • Eingeklappte Sub-Levels (Level 2+) auf Klick.
  • Pro Eintrag: Name, Status, Anzahl Conversions, generierte Provision.

Admin-Portal

Admin → Partner-Detail → Tab „Downline":

  • Tabellarische Ansicht mit Downline-Counts pro Level.
  • Rekursive Aggregation über alle Levels (auch wenn die Kampagne nur 3 Levels auszahlt, sieht Admin die echte Tiefe).

Lead-Affiliate-Programm

Partner können ihre Downline aktiv aufbauen, indem sie Sponsor-Links generieren:

https://<tenant>.partnerdesk.io/register?ref=<eigene-partner-id>

Klick → Self-Registration → Sponsor automatisch zugewiesen.

Details: 63 — Lead-Affiliate-Programm.

Downline-basierte Boni

Über das Bonus-System können Sie zusätzliche Belohnungen für aktive Werber konfigurieren:

  • referral_count: X aktive direkte Downline-Partner → einmaliger Bonus.
  • referral_revenue: Y € Downline-Umsatz in N Tagen → einmaliger Bonus.

Details: 13 — Bonusprogramme.

Verwandte Kapitel

Technische Tiefen-Doku: ../001-initial-setup.md (CommissionCalculator), ../019-default-template-and-resync.md (MLM-Tests), ../096-lead-affiliate-program.md