Ultimate Abo
Commerce.

Wer Verbrauchsartikel verkauft, möchte Stammkunden nicht jedes Mal neu zur Bestellung bewegen. Shopware bringt von Haus aus keine Abo-Verwaltung mit; Folgebestellungen von Hand anzulegen kostet Zeit und führt zu Fehlern bei Preis, Adresse und Zahlung.

Ultimate Abo Commerce legt beim Checkout für jeden Abo-Artikel einen Vertrag an. Er speichert Preis, Intervall, Adressen, Zahl- und Versandart. Zum Fälligkeitstag erzeugt das Plugin daraus eine normale Shopware-Bestellung. Schlägt etwas fehl, wiederholt das Plugin den Versuch nach Ihrem Plan und meldet sich in der Administration, wenn Sie eingreifen müssen.

Technischer Name: BmaniaUltimateAbo.

Installation:

1. bin/console plugin:refresh
2. bin/console plugin:install --activate BmaniaUltimateAbo
3. bin/console cache:clear

Ein Theme-Build ist nicht nötig, weil das Plugin in 1.0.1 nichts in der Storefront anzeigt.

Die ersten Schritte:

1. Hintergrundprozesse prüfen. Scheduled Tasks und Message-Queue-Worker müssen laufen; der Task „bmania_abo.dispatch_due_cycles“ läuft alle 600 Sekunden.
2. Ausführung einstellen. Ausführungszeit, Zeitzone und Wiederholplan festlegen (Kapitel 7).
3. Plan anlegen über die Admin-API, mit Intervallen, Rabatt und Produkten (Kapitel 4).
4. Testabo kaufen über die Store API, bezahlt mit Rechnung oder Vorkasse (Kapitel 5). An der Bestellung entsteht ein Vertrag „ABO-10000“.
5. Vorschau ansehen: bin/console bmania-abo:dry-run --until=JJJJ-MM-TT listet, welche Folgebestellungen bis dahin entstünden.

Wer Geld in regelmäßigen Abständen einzieht, braucht klare Regeln. Diese gelten in jedem Teil des Plugins:

• Ein Vertrag je Plan und Intervall. Zwei Artikel desselben Plans im selben Intervall ergeben einen Vertrag mit zwei Positionen; ein anderes Intervall ergibt einen eigenen Vertrag.
• Der Preis steht beim Abschluss fest. Spätere Preisänderungen am Produkt ändern laufende Verträge nicht. Steuern rechnet jede Folgebestellung neu für das Lieferland.
• Die Folgebestellung ist eine echte Bestellung. Bestandsprüfung, Versandkosten, Mails und Flows laufen wie bei jeder Bestellung.
• Nie zweimal belasten. Jede Periode existiert genau einmal, nur ein Worker darf sie bearbeiten.
• Nie still auf etwas anderes ausweichen. Fehlt etwas, scheitert die Periode mit einem Grund.
• Protokoll statt Radiergummi. Jede Statusänderung landet in einem Protokoll, das nur wächst.

Ein Plan legt fest, welche Produkte es im Abo gibt, in welchen Intervallen und zu welchem Rabatt. In 1.0.1 gibt es dafür noch kein Admin-Modul — Pläne entstehen über die Admin-API (Entität bmania_abo_plan), etwa mit einem Integrations-Zugang unter Einstellungen › System › Integrationen.

Die Felder, die in 1.0.1 wirken:

• name, description — Bezeichnung des Plans, übersetzbar.
• active — nur aktive Pläne sind kaufbar; laufende Verträge erneuern sich auch bei inaktivem Plan weiter.
• serviceType — Art der Leistung; „delivery“ für Lieferungen.
• purchaseMode — „subscription_or_once“ (Einzelkauf und Abo) oder „subscription_only“ (nur im Abo).
• intervals — freigegebene Intervalle: day, week, month oder year, Anzahl 1 bis 3650.
• discounts — Rabatt je Kundengruppe; Prozent in Basispunkten (1000 = 10 %), Festbetrag in Cent.
• allowedPaymentMethodIds — schränkt die Zahlarten weiter ein (nur Rechnung/Vorkasse möglich).
• oneIntervalPerCart — alle Abo-Artikel einer Bestellung müssen dasselbe Intervall haben.
• products — zugeordnete Produkte; Varianten erben die Zuordnung ihres Hauptprodukts.

Das Plugin prüft jeden Plan beim Speichern: Ungültige Werte weist die API mit einem eigenen Fehlercode ab. Ein trotzdem unlesbarer Plan wird im Warenkorb als „nicht verfügbar“ behandelt — nie als Fehler 500.

Ein Abo-Artikel ist eine normale Produktposition mit dem Zusatz „bmaniaAbo“ (Plan und Intervall). In 1.0.1 setzt das Ihr Frontend über die Store API — etwa in einem Headless-Shop oder einem angepassten Theme.

Das Plugin prüft Plan, Produkt, Intervall und Zahlart und setzt den Abo-Preis. Passt etwas nicht, sieht der Kunde eine Meldung:

• Abo nicht mehr verfügbar — Plan inaktiv, Produkt nicht im Plan oder Intervall nicht freigegeben. Der Artikel wird zum regären Preis als Einzelkauf berechnet; die Bestellung bleibt möglich.
• Zahlart nicht möglich — die gewählte Zahlart ist für Abos nicht freigegeben. Bestellung gesperrt.
• Nur im Abo erhältlich — der Plan steht auf „subscription_only“, der Artikel liegt als Einzelkauf im Warenkorb. Bestellung gesperrt.
• Anderes Intervall — „oneIntervalPerCart“ ist aktiv und die Abo-Artikel haben verschiedene Intervalle. Bestellung gesperrt.

Die Texte stehen unter Einstellungen › Shop › Textbausteine (Präfix „checkout.bmania-abo-“) und lassen sich dort anpassen.

1. Checkout — der Kunde bestellt einen Abo-Artikel mit Rechnung oder Vorkasse. Je Plan und Intervall entsteht ein Vertrag mit eigener Nummer (ABO-10000, ABO-10001 …), eigenen Adressen und festem Preis.
2. Erste Periode — die Erstbestellung ist die erste Periode; der Vertrag ist sofort aktiv.
3. Nächste Periode wird geplant — ein Intervall später, zur Ausführungszeit in der Shop-Zeitzone.
4. Folgebestellung — der Scheduler sieht alle zehn Minuten nach fälligen Perioden und legt die Bestellung mit den Vertragsdaten an. Sie löst die Flows für „Bestellung aufgegeben“ aus, also auch die Bestellbestätigung.
5. Zahlung — bei Rechnung und Vorkasse wartet die Periode auf den Zahlungseingang. Sobald Sie die Zahlung auf „Bezahlt“ setzen, ist die Periode bezahlt.

Status einer Periode: scheduled (geplant), processing (in Bearbeitung), awaiting_payment (Bestellung angelegt, Zahlung offen), retrying (fehlgeschlagen, nächster Versuch geplant), paid, failed, chargeback (zurückgebucht oder voll erstattet), cancelled.

Status eines Vertrags: active (läuft), payment_failed (Zahlung endgültig gescheitert; der Vertrag läuft weiter und wird nach der nächsten bezahlten Periode wieder aktiv), pending_activation (mit nicht abo-fähiger Zahlart entstanden — keine Folgebestellungen), terminated (Kunde gelöscht, Adressen anonymisiert).

Unter Erweiterungen › Meine Erweiterungen › Ultimate Abo › Konfiguration; jedes Feld lässt sich global oder je Verkaufskanal setzen.

• Alle Ausführungen anhalten (Not-Aus) — hält alles an, was Perioden ausführt (Standard: aus).
• Ausführungszeit (HH:MM) — Uhrzeit, ab der Perioden am Fälligkeitstag laufen; der Scheduler nimmt sie innerhalb von zehn Minuten auf (Standard: 06:00).
• Shop-Zeitzone — für Ausführungszeit und Fälligkeiten (Standard: Europe/Berlin).
• Erneut versuchen nach Fehlschlag — Tage nach Fälligkeit, kommagetrennt (Standard: 1,3,7).

Nach dem Speichern von Ausführungszeit oder Zeitzone terminiert das Plugin alle noch nicht begonnenen Perioden neu; laufende und auf Wiederholung wartende behalten ihren Termin. Ungültige Werte fallen auf den Standard zurück.

Scheitert eine Periode aus einem wiederholbaren Grund, versucht es das Plugin an den Tagen aus Ihrem Wiederholplan erneut — gerechnet ab dem Fälligkeitstag, frühestens eine Stunde nach dem Fehlschlag. Mit dem Standard 1,3,7 sind das drei weitere Versuche; danach wird die Periode „failed“ und die nächste geplant.

Wiederholbare Gründe: Zahlung gescheitert, Vertragszahlart im Kanal nicht mehr aktiv, Versandart nicht mehr aktiv, Produkt fehlt oder ist nicht lieferbar, Vertragsadresse fehlt (wird neu angelegt), Kundenkonto deaktiviert, sonstige Warenkorb-Sperre.

Nicht wiederholbar: Kunde gelöscht (der Vertrag endet), Folgebestellung storniert, Vertrag ohne Produktposition.

Was Ihre Eingriffe bewirken: Zahlung auf „Bezahlt“ setzen macht die Periode paid und einen Vertrag in payment_failed wieder aktiv. „Abgebrochen“ oder „Fehlgeschlagen“ löst die Wiederholung nach Plan aus. Eine Stornierung macht die Periode failed, der Vertrag läuft weiter. Eine Rückbuchung oder volle Erstattung setzt die Periode auf chargeback und den Vertrag auf payment_failed.

Mitteilungen erscheinen in der Glocke oben rechts, nur für Administratoren, mit Bestell- oder Vertragsnummer — derselbe Text höchstens einmal je Stunde. Sie melden unter anderem: kein Abo-Vertrag zu einer Bestellung (der Scheduler versucht es sieben Tage lang), ein zweimal fehlgeschlagener Folgeschritt, eine Periode länger als zwei Stunden in Bearbeitung (Worker prüfen) und nicht verteilbare fällige Perioden.

Log-Kanal: Das Plugin schreibt in eine eigene Datei, nicht ins Shopware-Log — var/log/bmania_abo_prod-JJJJ-MM-TT.log, mit Grund, Vertrags- und Periodennummer.

Probelauf: bin/console bmania-abo:dry-run --until=2026-12-31 ändert nichts und listet die Perioden, die bis dahin laufen würden — mit Vertrag, Termin und Betrag. Er meldet auch einen aktiven Not-Aus und ungültige Einstellungen.

Sprachen: Kundenmeldungen und Mitteilungen gibt es auf Deutsch und Englisch; andere Sprachen zeigen den englischen Text, bis Sie ihn in den Textbausteinen übersetzen.

Mehrere Server: Das Plugin sperrt jede Periode während der Bearbeitung. Mit Shopwares Standard-Lock-Store gilt diese Sperre nur auf einem Server — laufen Worker auf mehreren Servern, richten Sie einen gemeinsamen Lock-Store ein (z. B. Redis).

Updates spielen Sie wie gewohnt ein; Verträge und geplante Perioden bleiben erhalten.

Deinstallation: Mit „Daten behalten“ bleiben Pläne, Verträge, Perioden und Protokoll erhalten. Ohne Haken werden alle Abo-Tabellen, die Konfiguration und der Nummernkreis entfernt — laufende Abos enden damit ohne Folgebestellung. Alle Bestellungen bleiben, denn Erst- und Folgebestellungen sind normale Shopware-Bestellungen.

Das Plugin ist ein Werkzeug. Ob und wie Sie Abos rechtmäßig anbieten — Preisangaben, Vertragsbedingungen, Widerruf, Laufzeit und Kündigung —, entscheiden Sie, im Zweifel mit Ihrer Rechtsberatung.

Die Kontrollrunde vor dem Livegang:

1. Hintergrundprozesse — läuft der Task alle zehn Minuten, verarbeitet ein Worker die Message-Queue?
2. Testplan — richtiger Rabatt je Kundengruppe, nur die gewünschten Intervalle?
3. Testbestellung — steht an der Bestellung der Abo-Preis, ist ein Vertrag „ABO-…“ entstanden?
4. Probelauf bis nach dem ersten Intervall — richtiger Termin, Betrag und richtige Währung?
5. Folgebestellung im Testsystem erzeugen und Adresse, Preis, Steuer, Versandkosten und Kundenmail prüfen.
6. Texte lesen — Bestellbestätigung, Rechnung und die Warenkorb-Meldungen in allen Shop-Sprachen.

Im Shop sehe ich keine Abo-Auswahl. Woran liegt das? Das ist in 1.0.1 so vorgesehen — die Auswahl auf der Produktseite kommt mit der nächsten Version. Bis dahin legt Ihr Frontend Abo-Artikel über die Store API in den Warenkorb.

Es entstehen keine Folgebestellungen. Was prüfe ich zuerst? Fast immer die Hintergrundprozesse: Läuft der Scheduled Task, verarbeitet ein Worker die Queue? Danach den Not-Aus (global und je Verkaufskanal) und den Probelauf.

Ich habe den Produktpreis geändert. Zahlen Abo-Kunden jetzt mehr? Nein. Der Vertrag rechnet mit dem Preis der Erstbestellung; nur neue Abos zahlen den neuen Preis.

Der Kunde zahlt mit PayPal. Warum bekommt er keinen Abo-Preis? In 1.0.1 sind für Abos nur Rechnung und Vorkasse freigegeben. Mit einer anderen Zahlart sperrt der Warenkorb die Bestellung.

Wie beende ich ein einzelnes Abo? In 1.0.1 noch nicht über eine Funktion. Stornieren Sie eine Folgebestellung, entfällt diese eine Periode; der Vertrag läuft weiter. Der Not-Aus hält alle Abos eines Verkaufskanals an.

Wird ein Kunde doppelt belastet, wenn der Server während einer Folgebestellung abstürzt? Nein. Jede Periode gibt es genau einmal, und eine angelegte Bestellung wird beim nächsten Versuch wiedergefunden statt neu angelegt.

Wo bekomme ich Hilfe? Direkt bei der Gründerkind GmbH. Halten Sie Shopware-Version, Plugin-Version, die Vertragsnummer und den Auszug aus dem Log-Kanal bereit.