# Abonnementpläne

Die Subscription-Plans-API verwaltet vom Tenant definierte Pläne mit Listing-Kontingent eines Kontos, Ablaufzeitraum und Bestellgebühren oder Provisionen. Sie ist von der listingbasierten Memberships-API (`/v1/memberships`) getrennt, die für eigene Kunden- und Mitgliederprogramme gedacht ist.

Alle Beispiele verwenden Bearer-Authentifizierung. Tenant- und Benutzeridentität werden aus der authentifizierten Anfrage ermittelt; senden Sie keine zusätzlichen Identitätsheader.

```bash
export API="https://api.tradly.app"
export TOKEN="<bearer-token>"
```

## Abonnementpläne verwalten

- `GET /v1/subscription_products` listet für den Tenant sichtbare Pläne. Optionale Abfrageparameter: `currency_id`, `account_id` und `include_stats=true`. Nicht-Admins erhalten nur aktive Pläne und müssen den Währungskontext angeben.
- `GET /v1/subscription_products/{id}` gibt einen Plan zurück. Nicht-Admins können nur aktive Pläne abrufen und müssen den erforderlichen Währungskontext angeben.
- `POST /v1/subscription_products` erstellt einen Plan im Objekt `subscription_product`. Erforderlich sind `title`, `allowed_listings` (positive Ganzzahl), `currency_id`, `expiry_days` (positive Ganzzahl) und `type`. Unterstützte Werte: `free_subscription`, `stripe`, `android`, `ios`, `mangopay`.

```bash
curl -X POST "$API/v1/subscription_products" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  --data-raw '{"subscription_product":{"title":"Starter","description":"Starter plan","amount":49.00,"currency_id":13,"expiry_days":30,"allowed_listings":25,"type":"stripe","sku":"starter-monthly","active":true,"fee_fixed_per_order":0,"commission_percent_per_order":0,"metadata":{}}}'
```

Die Antwort enthält die neue `subscription_product.id`.

- `PUT /v1/subscription_products/{id}` aktualisiert den Plan mit demselben Objekt und den Pflichtfeldern. Akzeptiert `stripe`, `android`, `ios` oder `mangopay`; `free_subscription` wird vom Update-Validator nicht akzeptiert.
- `DELETE /v1/subscription_products/{id}` archiviert den Plan und setzt ihn inaktiv, ohne den Abonnementverlauf physisch zu löschen.

## Plananalysen

Alle Analyse-Routen sind auf den authentifizierten Tenant beschränkt.

| Methode | Endpunkt | Beschreibung |
|---|---|---|
| `GET` | `/v1/subscription_products/stats` | Aggregierte Planstatistiken des Tenants. |
| `GET` | `/v1/subscription_products/{id}/stats` | Statistiken eines Plans. |
| `GET` | `/v1/subscription_products/{id}/subscribers` | Paginierte Abonnenten; Filter `page`, `per_page` (max. 100) und `status` (`active`, `trial`, `expired`, `cancelled`). |
| `GET` | `/v1/subscription_products/{id}/invoices` | Paginierter Abrechnungsverlauf mit denselben Filtern; aus Abonnementdatensätzen abgeleitet, keine eigene Rechnungstabelle. |
| `GET` | `/v1/subscription_products/{id}/revenue` | Monatliche Reihen für Umsatz und Abonnentenzahl. |

Die Gesamtstatistiken umfassen aktive, gekündigte, abgelaufene und Probe-Abos, MRR/ARR, Kündigungsrate, Neuabschlüsse und Abgänge im aktuellen Monat, durchschnittliche Laufzeit gekündigter Abos sowie erfassten Gesamtumsatz. Diese Kennzahlen dienen dem operativen Überblick und ersetzen keine Buchhaltungsrechnungen oder das Hauptbuch.

## Kunden-Abonnementablauf

| Methode | Endpunkt | Zweck |
|---|---|---|
| `GET` | `/v1/subscriptions/subscribe/products?account_id={account_id}` | Verfügbare Pläne eines Kontos auflisten; optional nach `type` filtern. |
| `POST` | `/v1/subscriptions/subscribe` | Mobilkauf mit `account_id`, `subscription_product_id` und Beleg-`token` bestätigen; der Handler prüft iOS-/Android-Belege. |
| `POST` | `/v1/subscriptions/subscribe/confirm` | Mobilkauf mit denselben Pflichtfeldern bestätigen. |
| `POST` | `/v1/subscriptions/email_trigger` | Abonnement-Aufforderung an ein berechtigtes Konto (`account_id`) senden. |
| `DELETE` | `/v1/subscriptions/unsubscribe` | Abonnement eines Kontos (`account_id`) kündigen. |
| `GET` | `/v1/subscriptions/subscribe/manage?account_id={account_unique_id}&tenant_id={tenant_unique_id}` | Unterstützte Verwaltungsseite bzw. Kundenportal öffnen (derzeit Stripe). |

Kaufbestätigungen prüfen derzeit iOS- und Android-Belege. `stripe`-Pläne werden über diese Beleg-Endpunkte nicht bestätigt; verwenden Sie den konfigurierten Stripe-Checkout bzw. das Portal. Web-Übergabe-Endpunkte verwenden einen separaten älteren Vertrag und werden hier nicht als reine Bearer-Client-Beispiele gezeigt.

## Zugehörige APIs

- [Mitgliedschaften](memberships) — listingbasierte Mitgliedschaften, Beiträge und Preisprotokolle.
- [Listings](listings) — Listing-Pläne/Produkte und Checkout.