> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Abrechnungsstatus abrufen

> Gibt den aktuellen Abrechnungsstatus, den Funktionsmodus und die Nachfrist für den authentifizierten Mandanten zurück.

```http theme={null}
GET /v1/billing/status
```

Gibt den aktuellen Abrechnungsstatus Ihres Mandanten zurück. Verwenden Sie diesen Endpunkt in Ihrer Integration, um Zahlungsprobleme frühzeitig zu erkennen und Ihren Benutzern Aufforderungen anzuzeigen, bevor der Zugriff eingeschränkt wird.

Wenn alle Zahlungen aktuell sind, ist `feature_mode` `NORMAL` und `grace_until` ist `null`. Wenn eine Zahlung fehlschlägt, tritt das Konto in einen gestuften Zugriffs-Workflow ein – Herabgestuft, Eingeschränkt, dann Gesperrt – mit einer Schonfrist in jeder Phase.

## Antwort

**status** `string`

Der Status des Abrechnungskontos: `ACTIVE`, `PAST_DUE`, `UNPAID` oder `SUSPENDED`.

**feature\_mode** `string`

Die aktuelle Funktionsfähigkeit:

* `NORMAL` – alle Funktionen verfügbar
* `DEGRADED` – Zahlung fehlgeschlagen; alle Funktionen funktionieren während der Schonfrist weiterhin
* `RESTRICTED` – Schonfrist läuft ab; Schreibvorgänge (Prägen, Schlüsselerstellung) sind deaktiviert
* `SUSPENDED` – Schonfrist abgelaufen; der gesamte API-Zugriff ist deaktiviert, bis die Zahlung erfolgt ist

**grace\_until** `string | null`

ISO 8601 Zeitstempel, wann die aktuelle Nachfrist endet, oder `null`, wenn das Konto in gutem Zustand ist.

**banner** `string | null`

Eine menschenlesbare Nachricht, die die erforderliche Aktion beschreibt, oder `null`, wenn keine Aktion erforderlich ist.

## Wann dieser Endpunkt verwendet werden sollte

Verwenden Sie `GET /v1/billing/status`, um:

* **Zahlungsaufforderungen anzeigen** – überprüfen Sie `feature_mode` beim Start der App oder beim Login und zeigen Sie ein Banner an, wenn der Wert nicht `NORMAL` ist.
* **Schreiboperationen schützen** – vor dem Prägen oder Erstellen von Schlüsseln überprüfen, ob `feature_mode` nicht `RESTRICTED` oder `SUSPENDED` ist.
* **Kulanzfristen verfolgen** – lesen Sie `grace_until`, um Ihren Benutzern genau zu zeigen, wie lange sie Zeit haben, ein Zahlungsproblem zu lösen.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/billing/status", {
  headers: { "X-API-Key": "tl_live_..." },
});
const { feature_mode, grace_until } = await res.json();

if (feature_mode !== "NORMAL") {
  showPaymentBanner(feature_mode, grace_until);
}
```

## Kulanzzeitraum

Die Standard-Kulanzfristen für den Standard-Vertragsmodus sind:

| Übergang | Kulanzfrist | Benachrichtigungen |
| :- | :- | :- |
| NORMAL → DEGRADIERT | 7 Tage | Erinnerungen bei T+24h, T+48h, T+72h |
| DEGRADIERT → EINGESCHRÄNKT | 14 Tage | Erinnerungen bei T+24h, T+48h, T+72h |
| EINGESCHRÄNKT → GESPERRT | Sofort | Letzte Sperrbenachrichtigung |

Unternehmensverträge verlängern jedes Fenster um 14 zusätzliche Tage. Regierungsverträge verwenden eine feste 90-tägige Nachfrist ohne automatische Aussetzung. Details finden Sie unter [Vertragsmodi](https://docs.truthlocks.com/de/billing/overview.md#contract-modes).

> [!TIP]
>
> Eine vollständige Aufschlüsselung des gestuften Zugriffs-Workflows finden Sie unter [Zahlungsausfälle und Kulanzfristen](https://docs.truthlocks.com/de/billing/overview.md#payment-failures-and-grace-periods).


## OpenAPI

````yaml de/mint-openapi.yaml GET /v1/billing/status
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks ist eine universelle Verifizierungsinfrastruktur für Dokumente,
    Anmeldeinformationen und digitale Assets.

    Diese Spezifikation definiert die kanonische API für die Interaktion mit
    Truthlocks-Diensten.


    ## Basis-URLs

    - **Produktion**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Authentifizierung

    - **API-Schlüssel**: Verwenden Sie den Header `X-API-Key` für
    Machine-to-Machine-Operationen

    - **Bearer Tokens**: Verwenden Sie `Authorization: Bearer <jwt>` für
    benutzerinitiierte Operationen


    ## Mandantenidentität

    In der Produktion wird die Mandantenidentität aus dem authentifizierten
    Kontext (API-Schlüssel oder JWT) abgeleitet.

    Der Header `X-Tenant-ID` wird in der Produktion ignoriert, um Spoofing zu
    verhindern.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Produktions-API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox-Umgebung
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: API-Schlüssel- und Token-Verwaltung
  - name: Issuers
    description: Ausstellerregistrierung und Vertrauensmanagement
  - name: Keys
    description: Kryptographische Schlüsselverwaltung für Aussteller
  - name: Attestations
    description: Bestätigungslebenszyklus (prägen, widerrufen, ersetzen)
  - name: Verification
    description: Bestätigungsverifizierung und Proof-Bundles
  - name: Governance
    description: Aussteller-Governance-Workflows (nur Admin)
  - name: Identity
    description: Organisations-, Benutzer- und Rollenverwaltung
  - name: Audit
    description: Audit-Ereignisabfragen
  - name: Tenant Console
    description: Mandantenprofil- und Lebenszyklus-Endpunkte
  - name: Health
    description: Endpunkte für Dienststatus und Bereitschaft
  - name: Risk
    description: Erfassung von Risikosignalen und Betrugserkennung
  - name: Risk Enforcement
    description: >-
      Risikodurchsetzungsmaßnahmen – Blockieren, Herausfordern, Quarantäne und
      Konfiguration
  - name: Billing
    description: Verwaltung von Abrechnung, Abonnements und Add-ons
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) – Agentenregistrierung, Sitzungen,
      Vertrauen, Zeugen, Compliance, Orchestrierung und Beobachtbarkeit
externalDocs:
  description: Transparenz-API nur lesend (separate Dienstspezifikation)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/billing/status:
    get:
      tags:
        - Billing
      summary: Abrechnungsstatus abrufen
      description: >-
        Gibt den Abrechnungsstatus, den aktuellen Plan und die Feature-Flags für
        den authentifizierten Mandanten zurück.
      operationId: billing.status
      responses:
        '200':
          description: Abrechnungsstatus
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan:
                    type: string
                  status:
                    type: string
                  trial_ends_at:
                    nullable: true
                    type: string
        '401':
          description: Authentifizierung erforderlich
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Maschinenlesbarer Fehlercode
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Menschenlesbare Fehlermeldung
        http_status:
          type: integer
          description: HTTP-Statuscode
        retry_after_ms:
          type: integer
          description: >-
            Millisekunden, die vor einem erneuten Versuch gewartet werden sollen
            (für Ratenbegrenzungen)
        details:
          type: object
          description: Zusätzlicher Fehlerkontext
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API-Schlüssel für die Maschine-zu-Maschine-Authentifizierung
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT für benutzerinitiierte Operationen

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.