# Mitgliedschaften

Mit der Memberships-API können Tenants Benutzer für Programme anmelden, die an ein Listing vom Typ `membership` gebunden sind.

Jede Mitgliedschaft erfasst die Anmeldung eines Benutzers für ein Listing (mit tenant-eigener externer `membership_id`), Zahlungsbeiträge aus Tradly-Bestellungen und den Preisverlauf zur Berechnung gutgeschriebener Einheiten.

## Externe Mitglieds-ID

`membership_id` ist die eigene Mitglieder- oder Programmreferenz des Tenants (z. B. `GOLD-2026-00123`). Sie ist weder die Datenbank-`id` noch die Tradly-`user_id`. Verwenden Sie sie zur Zuordnung zu CRM- oder Abrechnungssystemen. Sie muss pro Tenant und Membership-Listing eindeutig sein und darf bis zu 128 Zeichen lang sein.

## Ablauf

1. Erstellen Sie über die Listings-API ein Listing vom Typ `membership`.
2. Melden Sie den Benutzer mit `POST /v1/memberships` an.
3. Bei einer Zahlung über den standardmäßigen Tradly-Checkout wird der Beitrag bei Bestellbestätigung automatisch erfasst.
4. Optional können Sie mit `POST /v1/memberships/price_logs` Preisverläufe für gutgeschriebene Einheiten protokollieren.

## Anfangsstatus

| Wert | Beschreibung |
|---|---|
| `active` | Mitgliedschaft ist aktiv (Standard) |
| `expired` | Das `end_date` ist verstrichen |
| `cancelled` | Mitgliedschaft wurde manuell beendet |

Lassen Sie `status` beim Erstellen weg, um mit `active` zu beginnen. Der Endpunkt speichert den übermittelten Status; Ablauf und Kündigung werden nicht automatisch umgestellt und müssen von Ihrer Anwendung verwaltet werden.

## Authentifizierung

Authentifizieren Sie sich mit `Authorization: Bearer <token>`. Tenant und Benutzer werden aus dem Token oder durch das Gateway ermittelt. Senden Sie keine separaten Header `tenant_id`, `user_id`, `admin` oder `X-Auth-Key`. Nicht-Admins können nur eigene Mitgliedschaften lesen und erstellen; Admins können Mitgliedschaften für beliebige Benutzer verwalten.