Stripe Abonnement-Management¶

Übersicht¶

Das Abonnement-System ermöglicht die Verwaltung von Stripe-Abonnements mit flexiblen Positionen (CustomerServices).

Datenmodell¶

`subscriptions` Tabelle¶

customer_id: Zugehöriger Kunde
name: Optional - Beschreibender Name des Abos
stripe_subscription_id: Stripe Subscription ID (nach Sync)
status: draft, active, synced, cancelled
billing_cycle: Abrechnungszyklus (monthly, quarterly, annually, etc.)
next_billing_date: Nächstes Abrechnungsdatum
stripe_synced_at: Zeitpunkt der letzten Synchronisation
notes: Notizen zum Abo

`subscription_items` Tabelle¶

subscription_id: Zugehöriges Abonnement
customer_service_id: Verknüpfter CustomerService
stripe_subscription_item_id: Stripe Item ID (nach Sync)
quantity: Anzahl/Menge
sort_order: Sortierreihenfolge

Beziehungen¶

Customer
├── Subscriptions (1:n)
    └── SubscriptionItems (1:n)
        └── CustomerService (1:1)

Workflow¶

1. Abonnement erstellen¶

Navigation: Admin Panel → Verwaltung → Abonnements → Neu erstellen

Kunde auswählen
Abrechnungszyklus festlegen
Nächstes Abrechnungsdatum setzen
Services als Items hinzufügen (z.B. Hosting + Domains + Emails)
Status: draft (Entwurf)

Wichtig: Das Abo wird zunächst nur lokal in HostAdmin angelegt, nicht automatisch zu Stripe synchronisiert.

2. Zu Stripe synchronisieren¶

In Bearbeitung des Abonnements: - Button "Zu Stripe syncen" (oben rechts) - Bestätigung erforderlich - Bei Erfolg: - stripe_subscription_id wird gespeichert - Status wechselt zu synced - stripe_synced_at wird aktualisiert

Voraussetzungen: - Status muss draft oder active sein - Noch nicht synchronisiert (kein stripe_subscription_id) - Stripe API Key konfiguriert

3. Abonnement bearbeiten¶

Services hinzufügen/entfernen
Quantities anpassen
TODO: Änderungen automatisch zu Stripe syncen

4. Abonnement löschen/kündigen¶

Lokales Löschen entfernt Abo aus HostAdmin
TODO: Bei synchronisierten Abos wird auch das Stripe-Abo gekündigt

Status-Übersicht¶

Status	Bedeutung	Stripe
`draft`	Entwurf, noch nicht aktiv	❌ Nicht synchronisiert
`active`	Aktiv, aber nicht synchronisiert	❌ Nicht synchronisiert
`synced`	Mit Stripe synchronisiert	✅ Synchronisiert
`cancelled`	Gekündigt	⚠️ Sollte auch in Stripe gekündigt sein

UI-Komponenten¶

Abonnements-Tabelle (Liste)¶

Kunde (Nummer + Name)
Name des Abos
Anzahl Services (Badge)
Abrechnungszyklus
Nächstes Abrechnungsdatum
Status (Badge mit Farbe)
Stripe-Sync-Indikator (✓/✗)

Abonnement-Formular¶

Grunddaten: Kunde, Name, Zyklus, Abrechnungsdatum, Status
Services: Repeater mit CustomerServices, Quantity
Stripe-Synchronisation: ReadOnly-Felder (ID, Sync-Zeit)
Notizen: Freitextfeld

Integration mit CustomerServices¶

Jeder CustomerService kann in mehreren Abonnements verwendet werden (über subscription_items).

Beispiel:

Abo 1 (Kunde A):
├── Service: Hosting Premium
├── Service: Domain example.com
└── Service: 5x E-Mail Postfächer (Quantity: 5)

Abo 2 (Kunde A):
└── Service: SSL Zertifikat (separates Abo)

Stripe API Integration (TODO)¶

Subscription erstellen¶

\Stripe\Subscription::create([
    'customer' => $customer->stripe_customer_id,
    'items' => [
        ['price' => $service->stripe_price_id, 'quantity' => $item->quantity],
        // weitere Items...
    ],
    'billing_cycle_anchor' => $subscription->next_billing_date->timestamp,
]);

Items hinzufügen/entfernen¶

\Stripe\SubscriptionItem::create([
    'subscription' => $subscription->stripe_subscription_id,
    'price' => $service->stripe_price_id,
    'quantity' => $quantity,
]);

Subscription kündigen¶

\Stripe\Subscription::update($subscription->stripe_subscription_id, [
    'cancel_at_period_end' => true,
]);

Webhooks (TODO)¶

Folgende Webhook-Events sollten verarbeitet werden:

customer.subscription.created: Abo wurde in Stripe erstellt
customer.subscription.updated: Abo wurde geändert (z.B. Items)
customer.subscription.deleted: Abo wurde gekündigt
invoice.payment_succeeded: Zahlung erfolgreich → Invoice erstellen
invoice.payment_failed: Zahlung fehlgeschlagen → Benachrichtigung

Admin Panel: - Verwaltung → Abonnements

Menü-Position: Nach "Services", vor "Rechnungen"

Berechtigungen¶

Nur Admin-Benutzer können Abonnements verwalten
Kunden sehen ihre Abonnements im Panel (TODO)

API Webhook Endpoint¶

URL: POST /api/stripe/webhook

Der Webhook empfängt Events von Stripe und verarbeitet diese automatisch.

Konfiguration in Stripe Dashboard¶

Gehe zu Developers → Webhooks
Füge Endpoint hinzu: https://your-domain.com/api/stripe/webhook
Wähle folgende Events:
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.payment_succeeded
invoice.payment_failed
Kopiere den Signing Secret in .env:
```
STRIPE_WEBHOOK_SECRET=whsec_...
```

Verarbeitete Events¶

Event	Aktion
`customer.subscription.created`	Status auf `synced` setzen
`customer.subscription.updated`	Status aktualisieren (z.B. bei Kündigung)
`customer.subscription.deleted`	Status auf `cancelled` setzen
`invoice.payment_succeeded`	TODO: Rechnung in HostAdmin erstellen
`invoice.payment_failed`	TODO: Benachrichtigung senden