usermembershipAPI-Referenz
POST
/v2/usermembershipMitgliedschaft für einen Benutzer kaufen
Kauft einen veröffentlichten oder intern zuweisbaren Plan für einen Benutzer des Kontos (source=admin_purchase). Erzeugt Mitgliedschaft, erste Periode und bei kostenpflichtigem Plan Buchhaltung/Rechnung mit pending_payment; kostenlose Käufe werden aktiviert oder geplant. Kein kostenloses Grant-API. idempotency_key verhindert doppelte Käufe desselben Ziels. Kontofähigkeit canPurchase, Planverfügbarkeit, Steuer und Parallelregel werden geprüft. Antwort enthält die vollständige Mitgliedschaft. Vor der Ausgabe werden verpasste Zahlungsrückmeldungen abgeglichen. Dadurch können Status, Gültigkeit, Nutzungsbestand und Zahlungsreferenzen sowie Audit/Outbox dauerhaft aktualisiert werden.
Operation-ID post_v2_usermembership
01
Vertrag & Verhalten
- Dokumentationsstand
- reviewed
- Ändert Zustand
- Ja
- Als readOnly markiert
- Nein
- Für Automation markiert
- Nein
02
Authentifizierung
Eine der folgenden Alternativen muss erfüllt sein (ODER). Innerhalb jeder Alternative werden alle angegebenen Schemas gemeinsam benötigt (UND).
Alternative 1
bearerAuthhttp · bearerExisting edoobox v2 access token. Never substitute API key/secret headers.
Format: JWT
Security-Schema als JSON
{
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Existing edoobox v2 access token. Never substitute API key/secret headers."
}accountContextapiKeySelected login/account context from the JWT, not a database primary key. Required even for a JWT with one account.
header: edid
Security-Schema als JSON
{
"type": "apiKey",
"in": "header",
"name": "edid",
"description": "Selected login/account context from the JWT, not a database primary key. Required even for a JWT with one account."
}Alternative 2
sessionCookieapiKeyExisting browser login session, with the same permission checks as Bearer authentication.
cookie: _edlogin
Security-Schema als JSON
{
"type": "apiKey",
"in": "cookie",
"name": "_edlogin",
"description": "Existing browser login session, with the same permission checks as Bearer authentication."
}accountContextapiKeySelected login/account context from the JWT, not a database primary key. Required even for a JWT with one account.
header: edid
Security-Schema als JSON
{
"type": "apiKey",
"in": "header",
"name": "edid",
"description": "Selected login/account context from the JWT, not a database primary key. Required even for a JWT with one account."
}03
Parameter
Header
X-Edoobox-If-RevisionoptionalOptional account mutation revision from a preceding authenticated auth-context snapshot. The dispatcher compares it while holding the account lock; mismatch409 requires a new review.
string
- pattern
"^[a-f0-9]{32}$"
Schema-Beispiel
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"Vollständiges Schema als JSON
{
"type": "string",
"pattern": "^[a-f0-9]{32}$",
"examples": [
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
]
}04
Request Body
erforderlichapplication/json
object
data object erforderlich user string erforderlich Öffentliche v2-ID des aktuellen Kontos.
- pattern
"^user_[a-f0-9]{12}_-?[0-9]+$"
plan string erforderlich Öffentliche v2-ID des aktuellen Kontos.
- pattern
"^membershipplan_[a-f0-9]{12}_-?[0-9]+$"
idempotency_key string erforderlich Clientseitig stabiler Schlüssel für genau diesen Vorgang; nach Whitespace-Trim 1–128 Zeichen.
- pattern
"^[A-Za-z0-9._:-]+$"- minLength
1- maxLength
128
activation_at integer | number | string | boolean Optionaler Unix-Zeitpunkt für Kauf/Aktivierung; Standard aktuelle Zeit, mindestens 1.
reason string Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
Vollständiges Schema als JSON
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"user": {
"type": "string",
"pattern": "^user_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"plan": {
"type": "string",
"pattern": "^membershipplan_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Clientseitig stabiler Schlüssel für genau diesen Vorgang; nach Whitespace-Trim 1–128 Zeichen."
},
"activation_at": {
"type": [
"integer",
"number",
"string",
"boolean"
],
"description": "Optionaler Unix-Zeitpunkt für Kauf/Aktivierung; Standard aktuelle Zeit, mindestens 1."
},
"reason": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"user",
"plan",
"idempotency_key"
]
}
},
"additionalProperties": true,
"required": [
"data"
]
}Mitgliedschaft für einen Benutzer kaufen
{
"data": {
"user": "user_012345abcdef_123456",
"plan": "membershipplan_012345abcdef_123456",
"idempotency_key": "demo-membership-purchase-001",
"reason": "Telefonische Bestellung"
}
}05
Antworten
11HTTP-Status und Antwortinhalt gemeinsam auswerten. In dieser API können auch Antworten mit HTTP 200 einen Fehler enthalten.
200application/json
data enthält das dokumentierte Ergebnis; error=false und success=true. Listen liefern zusätzlich total (Gesamtzahl vor Pagination).
Response Header
X-Edoobox-Revision
Rotated account revision supplied for the next action in one reviewed sequence.
string
- pattern
"^[a-f0-9]{32}$"
Vollständiges Schema als JSON
{
"type": "string",
"pattern": "^[a-f0-9]{32}$"
}application/json
object
success boolean error boolean | string error_code string data object id string erforderlich Öffentliche v2-ID des aktuellen Kontos.
- pattern
"^usermembership_[a-f0-9]{12}_-?[0-9]+$"
version integer erforderlich user string erforderlich Öffentliche v2-ID des aktuellen Kontos.
- pattern
"^user_[a-f0-9]{12}_-?[0-9]+$"
user_information object erforderlich name string erforderlich email string erforderlich Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
plan string erforderlich Öffentliche v2-ID des aktuellen Kontos.
- pattern
"^membershipplan_[a-f0-9]{12}_-?[0-9]+$"
plan_version integer erforderlich name string erforderlich status string erforderlich Erlaubte Werte
"pending_payment""scheduled""active""expired""exhausted""cancelled""payment_failed"active boolean erforderlich valid_from integer | null erforderlich valid_until integer | null erforderlich granted_uses integer | null erforderlich remaining_uses integer | null erforderlich membership_promo_code string | null erforderlich source string erforderlich renewal object erforderlich auto_renew boolean cancel_at_period_end boolean cancel_requested_at integer | null cancel_effective_at integer | null next_renewal_at integer | null Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
current_period string | null erforderlich Öffentliche v2-ID des aktuellen Kontos.
- pattern
"^membershipperiod_[a-f0-9]{12}_-?[0-9]+$"
created_at integer erforderlich updated_at integer erforderlich plan_snapshot object | array erforderlich Gespeicherter, versionsabhängiger Kaufsnapshot. Enthält ggf. weitere öffentliche Kauf-/Rechtskonfiguration; interne vat_id/design_id werden in v2-Referenzen umgewandelt.
name string validity object type string Erlaubte Werte
"fixed_range""relative_duration""usage_count"from integer | null until integer | null value integer | null unit string | null uses integer | null promo_code_redemption boolean Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
discount object type string Erlaubte Werte
"percent""fixed"value string Dezimalbetrag als String mit zwei Nachkommastellen.
- pattern
"^-?[0-9]+\\.[0-9]{2}$"
currency string | null Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
sale object amount string Dezimalbetrag als String mit zwei Nachkommastellen.
- pattern
"^-?[0-9]+\\.[0-9]{2}$"
currency string vat string | null Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID.
- pattern
"^vat_[a-f0-9]{12}_-?[0-9]+$"
Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
renewal object Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
design string | null Öffentliche v2-ID des aktuellen Kontos.
- pattern
"^design_[a-f0-9]{12}_-?[0-9]+$"
Array-Elemente
Typ nicht eingeschränkt
Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
periods array erforderlich Array-Elemente
object
id string erforderlich Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID.
- pattern
"^membershipperiod_[a-f0-9]{12}_-?[0-9]+$"
membership string erforderlich Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID.
- pattern
"^usermembership_[a-f0-9]{12}_-?[0-9]+$"
type string erforderlich period_start integer | null erforderlich period_end integer | null erforderlich payment_status string erforderlich amounts object erforderlich gross string erforderlich Dezimalbetrag als String mit zwei Nachkommastellen.
- pattern
"^-?[0-9]+\\.[0-9]{2}$"
net string erforderlich Dezimalbetrag als String mit zwei Nachkommastellen.
- pattern
"^-?[0-9]+\\.[0-9]{2}$"
tax string erforderlich Dezimalbetrag als String mit zwei Nachkommastellen.
- pattern
"^-?[0-9]+\\.[0-9]{2}$"
currency string erforderlich Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
vat object erforderlich id string | null erforderlich Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID.
- pattern
"^vat_[a-f0-9]{12}_-?[0-9]+$"
rate string erforderlich label string erforderlich Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
title string erforderlich plan_version integer erforderlich design string | null erforderlich Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID.
- pattern
"^design_[a-f0-9]{12}_-?[0-9]+$"
transaction string | null erforderlich Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID.
- pattern
"^transaction_[a-f0-9]{12}_-?[0-9]+$"
invoice string | null erforderlich Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID.
- pattern
"^invoice_[a-f0-9]{12}_-?[0-9]+$"
invoice_number string | null erforderlich payment string | null erforderlich Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID.
- pattern
"^pay_[a-f0-9]{12}_-?[0-9]+$"
reminder_due_at integer | null erforderlich renewal_due_at integer | null erforderlich created_at integer erforderlich updated_at integer erforderlich Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
ledger_summary object erforderlich balance integer erforderlich events integer erforderlich Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
type string Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
Vollständiges Schema als JSON
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": [
"boolean",
"string"
]
},
"error_code": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^usermembership_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"version": {
"type": "integer"
},
"user": {
"type": "string",
"pattern": "^user_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"user_information": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"name",
"email"
]
},
"plan": {
"type": "string",
"pattern": "^membershipplan_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"plan_version": {
"type": "integer"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending_payment",
"scheduled",
"active",
"expired",
"exhausted",
"cancelled",
"payment_failed"
]
},
"active": {
"type": "boolean"
},
"valid_from": {
"type": [
"integer",
"null"
]
},
"valid_until": {
"type": [
"integer",
"null"
]
},
"granted_uses": {
"type": [
"integer",
"null"
]
},
"remaining_uses": {
"type": [
"integer",
"null"
]
},
"membership_promo_code": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"renewal": {
"type": "object",
"properties": {
"auto_renew": {
"type": "boolean"
},
"cancel_at_period_end": {
"type": "boolean"
},
"cancel_requested_at": {
"type": [
"integer",
"null"
]
},
"cancel_effective_at": {
"type": [
"integer",
"null"
]
},
"next_renewal_at": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
},
"current_period": {
"type": [
"string",
"null"
],
"pattern": "^membershipperiod_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
},
"plan_snapshot": {
"type": [
"object",
"array"
],
"properties": {
"name": {
"type": "string"
},
"validity": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"fixed_range",
"relative_duration",
"usage_count"
]
},
"from": {
"type": [
"integer",
"null"
]
},
"until": {
"type": [
"integer",
"null"
]
},
"value": {
"type": [
"integer",
"null"
]
},
"unit": {
"type": [
"string",
"null"
]
},
"uses": {
"type": [
"integer",
"null"
]
},
"promo_code_redemption": {
"type": "boolean"
}
},
"additionalProperties": true
},
"discount": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"percent",
"fixed"
]
},
"value": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"currency": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"sale": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"currency": {
"type": "string"
},
"vat": {
"type": [
"string",
"null"
],
"pattern": "^vat_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
}
},
"additionalProperties": true
},
"renewal": {
"type": "object",
"additionalProperties": true
},
"design": {
"type": [
"string",
"null"
],
"pattern": "^design_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
}
},
"additionalProperties": true,
"items": {},
"description": "Gespeicherter, versionsabhängiger Kaufsnapshot. Enthält ggf. weitere öffentliche Kauf-/Rechtskonfiguration; interne vat_id/design_id werden in v2-Referenzen umgewandelt."
},
"periods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^membershipperiod_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"membership": {
"type": "string",
"pattern": "^usermembership_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"type": {
"type": "string"
},
"period_start": {
"type": [
"integer",
"null"
]
},
"period_end": {
"type": [
"integer",
"null"
]
},
"payment_status": {
"type": "string"
},
"amounts": {
"type": "object",
"properties": {
"gross": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"net": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"tax": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"currency": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"gross",
"net",
"tax",
"currency"
]
},
"vat": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"pattern": "^vat_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"rate": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"id",
"rate",
"label"
]
},
"title": {
"type": "string"
},
"plan_version": {
"type": "integer"
},
"design": {
"type": [
"string",
"null"
],
"pattern": "^design_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"transaction": {
"type": [
"string",
"null"
],
"pattern": "^transaction_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"invoice": {
"type": [
"string",
"null"
],
"pattern": "^invoice_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"invoice_number": {
"type": [
"string",
"null"
]
},
"payment": {
"type": [
"string",
"null"
],
"pattern": "^pay_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"reminder_due_at": {
"type": [
"integer",
"null"
]
},
"renewal_due_at": {
"type": [
"integer",
"null"
]
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
}
},
"additionalProperties": true,
"required": [
"id",
"membership",
"type",
"period_start",
"period_end",
"payment_status",
"amounts",
"vat",
"title",
"plan_version",
"design",
"transaction",
"invoice",
"invoice_number",
"payment",
"reminder_due_at",
"renewal_due_at",
"created_at",
"updated_at"
]
}
},
"ledger_summary": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"events": {
"type": "integer"
}
},
"additionalProperties": true,
"required": [
"balance",
"events"
]
}
},
"additionalProperties": true,
"required": [
"id",
"version",
"user",
"user_information",
"plan",
"plan_version",
"name",
"status",
"active",
"valid_from",
"valid_until",
"granted_uses",
"remaining_uses",
"membership_promo_code",
"source",
"renewal",
"current_period",
"created_at",
"updated_at",
"plan_snapshot",
"periods",
"ledger_summary"
]
},
"type": {
"type": "string"
}
},
"additionalProperties": true
}Beispiel
{
"success": true,
"error": false,
"data": {
"id": "usermembership_012345abcdef_123456",
"version": 1,
"user": "user_012345abcdef_123456",
"user_information": {
"name": "",
"email": ""
},
"plan": "membershipplan_012345abcdef_123456",
"plan_version": 1,
"name": "Jahresmitgliedschaft",
"status": "pending_payment",
"active": false,
"valid_from": null,
"valid_until": null,
"granted_uses": null,
"remaining_uses": null,
"membership_promo_code": null,
"source": "admin_purchase",
"renewal": {
"auto_renew": false,
"cancel_at_period_end": false,
"cancel_requested_at": null,
"cancel_effective_at": null,
"next_renewal_at": null
},
"current_period": "membershipperiod_012345abcdef_123456",
"created_at": 1790000000,
"updated_at": 1790000000,
"plan_snapshot": {
"name": "Jahresmitgliedschaft",
"validity": {
"type": "relative_duration",
"from": null,
"until": null,
"value": 1,
"unit": "year",
"uses": null,
"promo_code_redemption": false
},
"discount": {
"type": "percent",
"value": "10.00",
"currency": null
},
"sale": {
"amount": "120.00",
"currency": "CHF",
"vat": null
}
},
"periods": [
{
"id": "membershipperiod_012345abcdef_123456",
"membership": "usermembership_012345abcdef_123456",
"type": "initial",
"period_start": null,
"period_end": null,
"payment_status": "pending",
"amounts": {
"gross": "120.00",
"net": "111.01",
"tax": "8.99",
"currency": "CHF"
},
"vat": {
"id": null,
"rate": "0.0000",
"label": ""
},
"title": "Jahresmitgliedschaft",
"plan_version": 1,
"design": null,
"transaction": "transaction_012345abcdef_123456",
"invoice": "invoice_012345abcdef_123456",
"invoice_number": "DEMO-2026-001",
"payment": null,
"reminder_due_at": 1818944000,
"renewal_due_at": 1821536000,
"created_at": 1790000000,
"updated_at": 1790000000
}
],
"ledger_summary": {
"balance": 0,
"events": 0
}
}
}400application/json
Invalid request.
application/json
Typ nicht eingeschränkt
Kein Schema angegeben. Daraus lässt sich kein vollständiger Feldvertrag ableiten.
Beispiel
{
"success": false,
"error": "ED40006"
}401application/json
Missing/expired token, missing account context, account paused or model-specific authorization failure.
application/json
Typ nicht eingeschränkt
Kein Schema angegeben. Daraus lässt sich kein vollständiger Feldvertrag ableiten.
Beispiel
{
"success": false,
"error": "ED40103"
}402application/json
Missing/invalid action data or subscription/operation restriction.
application/json
Typ nicht eingeschränkt
Kein Schema angegeben. Daraus lässt sich kein vollständiger Feldvertrag ableiten.
Beispiel
{
"success": false,
"error": "ED80100"
}403application/json
Permission denied. Browser CORS rejection may have an empty body.
application/json
Typ nicht eingeschränkt
Kein Schema angegeben. Daraus lässt sich kein vollständiger Feldvertrag ableiten.
Beispiel
{
"success": false,
"error": "ED40340"
}404application/json
Unknown resource/action or unsupported method.
application/json
Typ nicht eingeschränkt
Kein Schema angegeben. Daraus lässt sich kein vollständiger Feldvertrag ableiten.
Beispiel
{
"success": false,
"error": "ED80019"
}409application/json
The account changed after the reviewed read. No domain operation is dispatched; obtain fresh state and review again.
application/json
object
Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
Vollständiges Schema als JSON
{
"type": "object",
"additionalProperties": true
}Beispiel
{
"error": "ED40901",
"error_code": "mutation_revision_conflict"
}422application/json
Validation failed.
application/json
Typ nicht eingeschränkt
Kein Schema angegeben. Daraus lässt sich kein vollständiger Feldvertrag ableiten.
Beispiel
{
"success": false,
"error": "ED80020"
}429application/json
Request/login rate limit exceeded. Honor Retry-After when supplied; legacy rate-limit paths may omit it. Retry only proven reads within a bounded deadline; a mutation is never automatically replayed after an ambiguous response.
Response Header
Retry-After
Optional server delay in whole seconds or an HTTP date. Absence is not permission for an immediate retry.
string
Schema-Beispiel
"30"Vollständiges Schema als JSON
{
"type": "string",
"examples": [
"30"
]
}application/json
Typ nicht eingeschränkt
Kein Schema angegeben. Daraus lässt sich kein vollständiger Feldvertrag ableiten.
Beispiel
{
"success": false,
"error": "ED42902"
}502application/json
Server-side operation failed.
application/json
Typ nicht eingeschränkt
Kein Schema angegeben. Daraus lässt sich kein vollständiger Feldvertrag ableiten.
Beispiel
{
"success": false,
"error": "ED50201"
}503application/json
The account mutation lock or revision store is unavailable. No unprotected fallback is executed.
Response Header
Retry-After
integer
Fester Wert: 1
Vollständiges Schema als JSON
{
"type": "integer",
"const": 1
}application/json
object
Zusätzliche, hier nicht aufgeführte Felder sind erlaubt.
Vollständiges Schema als JSON
{
"type": "object",
"additionalProperties": true
}Beispiel
{
"error": "ED50301",
"error_code": "mutation_revision_busy"
}06
Quelle & Metadaten
Quelle laut Spezifikation
application/models/v2/Usermembership.php:117postUsermembership()Diese Angaben stammen unverändert aus der gelieferten OpenAPI-Datei. Zusätzliche Freigaben, Vorbedingungen, sensible Felder und Hinweise stehen in den Erweiterungen.
x-edoobox-mutates-state
truex-edoobox-runtimeMutationGuard
truex-edoobox-documentationReview
{
"file": "docs/openapi/operation-contracts/01-membership.json",
"notes": []
}x-edoobox-source
{
"file": "application/models/v2/Usermembership.php",
"method": "postUsermembership",
"line": 117
}x-edoobox-documentationStatus
"reviewed"x-edoobox-readOnly
falsex-edoobox-safeForAutomation
falsex-edoobox-permission
{
"resource": "usermembership",
"short": "usme",
"checkedByDispatcher": true,
"levels": [
2,
3,
4
],
"description": "Resource permission mapping from APIPermissions(), Authfunc::_getCheckJWT. Additional model/admin/plugin checks may apply; resources absent from api_permission do not acquire a fictitious scope."
}Vollständige Operation als JSON
{
"operationId": "post_v2_usermembership",
"summary": "Mitgliedschaft für einen Benutzer kaufen",
"description": "Kauft einen veröffentlichten oder intern zuweisbaren Plan für einen Benutzer des Kontos (source=admin_purchase). Erzeugt Mitgliedschaft, erste Periode und bei kostenpflichtigem Plan Buchhaltung/Rechnung mit pending_payment; kostenlose Käufe werden aktiviert oder geplant. Kein kostenloses Grant-API. idempotency_key verhindert doppelte Käufe desselben Ziels. Kontofähigkeit canPurchase, Planverfügbarkeit, Steuer und Parallelregel werden geprüft. Antwort enthält die vollständige Mitgliedschaft. Vor der Ausgabe werden verpasste Zahlungsrückmeldungen abgeglichen. Dadurch können Status, Gültigkeit, Nutzungsbestand und Zahlungsreferenzen sowie Audit/Outbox dauerhaft aktualisiert werden.",
"tags": [
"usermembership"
],
"security": [
{
"bearerAuth": [],
"accountContext": []
},
{
"sessionCookie": [],
"accountContext": []
}
],
"parameters": [
{
"name": "X-Edoobox-If-Revision",
"in": "header",
"required": false,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{32}$",
"examples": [
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
]
},
"description": "Optional account mutation revision from a preceding authenticated auth-context snapshot. The dispatcher compares it while holding the account lock; mismatch409 requires a new review."
}
],
"responses": {
"200": {
"description": "data enthält das dokumentierte Ergebnis; error=false und success=true. Listen liefern zusätzlich total (Gesamtzahl vor Pagination).",
"content": {
"application/json": {
"example": {
"success": true,
"error": false,
"data": {
"id": "usermembership_012345abcdef_123456",
"version": 1,
"user": "user_012345abcdef_123456",
"user_information": {
"name": "",
"email": ""
},
"plan": "membershipplan_012345abcdef_123456",
"plan_version": 1,
"name": "Jahresmitgliedschaft",
"status": "pending_payment",
"active": false,
"valid_from": null,
"valid_until": null,
"granted_uses": null,
"remaining_uses": null,
"membership_promo_code": null,
"source": "admin_purchase",
"renewal": {
"auto_renew": false,
"cancel_at_period_end": false,
"cancel_requested_at": null,
"cancel_effective_at": null,
"next_renewal_at": null
},
"current_period": "membershipperiod_012345abcdef_123456",
"created_at": 1790000000,
"updated_at": 1790000000,
"plan_snapshot": {
"name": "Jahresmitgliedschaft",
"validity": {
"type": "relative_duration",
"from": null,
"until": null,
"value": 1,
"unit": "year",
"uses": null,
"promo_code_redemption": false
},
"discount": {
"type": "percent",
"value": "10.00",
"currency": null
},
"sale": {
"amount": "120.00",
"currency": "CHF",
"vat": null
}
},
"periods": [
{
"id": "membershipperiod_012345abcdef_123456",
"membership": "usermembership_012345abcdef_123456",
"type": "initial",
"period_start": null,
"period_end": null,
"payment_status": "pending",
"amounts": {
"gross": "120.00",
"net": "111.01",
"tax": "8.99",
"currency": "CHF"
},
"vat": {
"id": null,
"rate": "0.0000",
"label": ""
},
"title": "Jahresmitgliedschaft",
"plan_version": 1,
"design": null,
"transaction": "transaction_012345abcdef_123456",
"invoice": "invoice_012345abcdef_123456",
"invoice_number": "DEMO-2026-001",
"payment": null,
"reminder_due_at": 1818944000,
"renewal_due_at": 1821536000,
"created_at": 1790000000,
"updated_at": 1790000000
}
],
"ledger_summary": {
"balance": 0,
"events": 0
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": [
"boolean",
"string"
]
},
"error_code": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^usermembership_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"version": {
"type": "integer"
},
"user": {
"type": "string",
"pattern": "^user_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"user_information": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"name",
"email"
]
},
"plan": {
"type": "string",
"pattern": "^membershipplan_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"plan_version": {
"type": "integer"
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending_payment",
"scheduled",
"active",
"expired",
"exhausted",
"cancelled",
"payment_failed"
]
},
"active": {
"type": "boolean"
},
"valid_from": {
"type": [
"integer",
"null"
]
},
"valid_until": {
"type": [
"integer",
"null"
]
},
"granted_uses": {
"type": [
"integer",
"null"
]
},
"remaining_uses": {
"type": [
"integer",
"null"
]
},
"membership_promo_code": {
"type": [
"string",
"null"
]
},
"source": {
"type": "string"
},
"renewal": {
"type": "object",
"properties": {
"auto_renew": {
"type": "boolean"
},
"cancel_at_period_end": {
"type": "boolean"
},
"cancel_requested_at": {
"type": [
"integer",
"null"
]
},
"cancel_effective_at": {
"type": [
"integer",
"null"
]
},
"next_renewal_at": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
},
"current_period": {
"type": [
"string",
"null"
],
"pattern": "^membershipperiod_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
},
"plan_snapshot": {
"type": [
"object",
"array"
],
"properties": {
"name": {
"type": "string"
},
"validity": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"fixed_range",
"relative_duration",
"usage_count"
]
},
"from": {
"type": [
"integer",
"null"
]
},
"until": {
"type": [
"integer",
"null"
]
},
"value": {
"type": [
"integer",
"null"
]
},
"unit": {
"type": [
"string",
"null"
]
},
"uses": {
"type": [
"integer",
"null"
]
},
"promo_code_redemption": {
"type": "boolean"
}
},
"additionalProperties": true
},
"discount": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"percent",
"fixed"
]
},
"value": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"currency": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"sale": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"currency": {
"type": "string"
},
"vat": {
"type": [
"string",
"null"
],
"pattern": "^vat_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
}
},
"additionalProperties": true
},
"renewal": {
"type": "object",
"additionalProperties": true
},
"design": {
"type": [
"string",
"null"
],
"pattern": "^design_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
}
},
"additionalProperties": true,
"items": {},
"description": "Gespeicherter, versionsabhängiger Kaufsnapshot. Enthält ggf. weitere öffentliche Kauf-/Rechtskonfiguration; interne vat_id/design_id werden in v2-Referenzen umgewandelt."
},
"periods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^membershipperiod_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"membership": {
"type": "string",
"pattern": "^usermembership_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"type": {
"type": "string"
},
"period_start": {
"type": [
"integer",
"null"
]
},
"period_end": {
"type": [
"integer",
"null"
]
},
"payment_status": {
"type": "string"
},
"amounts": {
"type": "object",
"properties": {
"gross": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"net": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"tax": {
"type": "string",
"pattern": "^-?[0-9]+\\.[0-9]{2}$",
"description": "Dezimalbetrag als String mit zwei Nachkommastellen."
},
"currency": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"gross",
"net",
"tax",
"currency"
]
},
"vat": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"pattern": "^vat_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"rate": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"id",
"rate",
"label"
]
},
"title": {
"type": "string"
},
"plan_version": {
"type": "integer"
},
"design": {
"type": [
"string",
"null"
],
"pattern": "^design_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"transaction": {
"type": [
"string",
"null"
],
"pattern": "^transaction_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"invoice": {
"type": [
"string",
"null"
],
"pattern": "^invoice_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"invoice_number": {
"type": [
"string",
"null"
]
},
"payment": {
"type": [
"string",
"null"
],
"pattern": "^pay_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID aus diesem Konto; keine rohe Datenbank-ID."
},
"reminder_due_at": {
"type": [
"integer",
"null"
]
},
"renewal_due_at": {
"type": [
"integer",
"null"
]
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
}
},
"additionalProperties": true,
"required": [
"id",
"membership",
"type",
"period_start",
"period_end",
"payment_status",
"amounts",
"vat",
"title",
"plan_version",
"design",
"transaction",
"invoice",
"invoice_number",
"payment",
"reminder_due_at",
"renewal_due_at",
"created_at",
"updated_at"
]
}
},
"ledger_summary": {
"type": "object",
"properties": {
"balance": {
"type": "integer"
},
"events": {
"type": "integer"
}
},
"additionalProperties": true,
"required": [
"balance",
"events"
]
}
},
"additionalProperties": true,
"required": [
"id",
"version",
"user",
"user_information",
"plan",
"plan_version",
"name",
"status",
"active",
"valid_from",
"valid_until",
"granted_uses",
"remaining_uses",
"membership_promo_code",
"source",
"renewal",
"current_period",
"created_at",
"updated_at",
"plan_snapshot",
"periods",
"ledger_summary"
]
},
"type": {
"type": "string"
}
},
"additionalProperties": true
}
}
},
"headers": {
"X-Edoobox-Revision": {
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{32}$"
},
"description": "Rotated account revision supplied for the next action in one reviewed sequence."
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"example": {
"success": false,
"error": "ED40006"
}
}
}
},
"401": {
"description": "Missing/expired token, missing account context, account paused or model-specific authorization failure.",
"content": {
"application/json": {
"example": {
"success": false,
"error": "ED40103"
}
}
}
},
"402": {
"description": "Missing/invalid action data or subscription/operation restriction.",
"content": {
"application/json": {
"example": {
"success": false,
"error": "ED80100"
}
}
}
},
"403": {
"description": "Permission denied. Browser CORS rejection may have an empty body.",
"content": {
"application/json": {
"example": {
"success": false,
"error": "ED40340"
}
}
}
},
"404": {
"description": "Unknown resource/action or unsupported method.",
"content": {
"application/json": {
"example": {
"success": false,
"error": "ED80019"
}
}
}
},
"409": {
"description": "The account changed after the reviewed read. No domain operation is dispatched; obtain fresh state and review again.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "ED40901",
"error_code": "mutation_revision_conflict"
}
}
}
},
"422": {
"description": "Validation failed.",
"content": {
"application/json": {
"example": {
"success": false,
"error": "ED80020"
}
}
}
},
"429": {
"description": "Request/login rate limit exceeded. Honor Retry-After when supplied; legacy rate-limit paths may omit it. Retry only proven reads within a bounded deadline; a mutation is never automatically replayed after an ambiguous response.",
"content": {
"application/json": {
"example": {
"success": false,
"error": "ED42902"
}
}
},
"headers": {
"Retry-After": {
"description": "Optional server delay in whole seconds or an HTTP date. Absence is not permission for an immediate retry.",
"schema": {
"type": "string",
"examples": [
"30"
]
}
}
}
},
"502": {
"description": "Server-side operation failed.",
"content": {
"application/json": {
"example": {
"success": false,
"error": "ED50201"
}
}
}
},
"503": {
"description": "The account mutation lock or revision store is unavailable. No unprotected fallback is executed.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"const": 1
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"example": {
"error": "ED50301",
"error_code": "mutation_revision_busy"
}
}
}
}
},
"x-edoobox-mutates-state": true,
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"user": {
"type": "string",
"pattern": "^user_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"plan": {
"type": "string",
"pattern": "^membershipplan_[a-f0-9]{12}_-?[0-9]+$",
"description": "Öffentliche v2-ID des aktuellen Kontos."
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$",
"description": "Clientseitig stabiler Schlüssel für genau diesen Vorgang; nach Whitespace-Trim 1–128 Zeichen."
},
"activation_at": {
"type": [
"integer",
"number",
"string",
"boolean"
],
"description": "Optionaler Unix-Zeitpunkt für Kauf/Aktivierung; Standard aktuelle Zeit, mindestens 1."
},
"reason": {
"type": "string"
}
},
"additionalProperties": true,
"required": [
"user",
"plan",
"idempotency_key"
]
}
},
"additionalProperties": true,
"required": [
"data"
]
},
"examples": {
"request": {
"summary": "Mitgliedschaft für einen Benutzer kaufen",
"value": {
"data": {
"user": "user_012345abcdef_123456",
"plan": "membershipplan_012345abcdef_123456",
"idempotency_key": "demo-membership-purchase-001",
"reason": "Telefonische Bestellung"
}
}
}
}
}
}
},
"x-edoobox-runtimeMutationGuard": true,
"x-edoobox-documentationReview": {
"file": "docs/openapi/operation-contracts/01-membership.json",
"notes": []
},
"x-edoobox-source": {
"file": "application/models/v2/Usermembership.php",
"method": "postUsermembership",
"line": 117
},
"x-edoobox-documentationStatus": "reviewed",
"x-edoobox-readOnly": false,
"x-edoobox-safeForAutomation": false,
"x-edoobox-permission": {
"resource": "usermembership",
"short": "usme",
"checkedByDispatcher": true,
"levels": [
2,
3,
4
],
"description": "Resource permission mapping from APIPermissions(), Authfunc::_getCheckJWT. Additional model/admin/plugin checks may apply; resources absent from api_permission do not acquire a fictitious scope."
}
}