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

# Guthaben & Abrechnung

> Überprüfe dein Guthaben und kaufe Guthabenaufladungen programmatisch.

Verwende die Endpunkte der Benutzerabrechnung, um das Guthaben deines Teams abzulesen und Aufladungen mit einer gespeicherten Zahlungsmethode zu kaufen. Beide Endpunkte erfordern eine Authentifizierung mit deinem [API-Schlüssel](/get-started/authentication). Ungültige Schlüssel geben **402** zurück.

## Guthaben überprüfen

`GET /user/credits/info` gibt das Guthaben des authentifizierten Teams, eine Aufschlüsselung pro Los, aktive Abonnementdetails und ob die Nutzung erlaubt ist, zurück.

Verwende diesen Endpunkt, um Abrechnungs-Widgets, Nutzungs-Dashboards oder Vorabprüfungen vor großen Jobs zu betreiben.

Für API-Details siehe [Guthabeninformationen abrufen](/api-reference/billing/credits-info).

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.olostep.com/user/credits/info",
      headers={"Authorization": "Bearer <API-TOKEN>"},
  )
  print(response.json())
  ```

  ```js Node theme={null}
  const res = await fetch("https://api.olostep.com/user/credits/info", {
    headers: { Authorization: "Bearer <API-TOKEN>" },
  })
  console.log(await res.json())
  ```

  ```bash cURL theme={null}
  curl -s "https://api.olostep.com/user/credits/info" \
    -H "Authorization: Bearer <API-TOKEN>"
  ```
</CodeGroup>

### Antwort

```json theme={null}
{
  "credits": 12500,
  "breakdown": [
    {
      "purchase_kind": "Subscription",
      "allocated_units": 10000,
      "remaining_units": 8500,
      "expiry_date": 1735689600
    },
    {
      "purchase_kind": "Top-up",
      "allocated_units": 5000,
      "remaining_units": 4000,
      "expiry_date": 1743465600
    }
  ],
  "active_subscription": {
    "id": "SUB_PRO",
    "display_name": "Pro",
    "credits": 10000,
    "created_at": 1704067200
  },
  "allow_usage": true
}
```

| Feld                  | Beschreibung                                                             |
| --------------------- | ------------------------------------------------------------------------ |
| `credits`             | Gesamt verbleibende Guthaben über alle nicht abgelaufenen Lose           |
| `breakdown`           | Detail pro Los: Typ, zugewiesene und verbleibende Einheiten, Ablaufdatum |
| `active_subscription` | Aktueller Plan (fällt auf `SUB_BASE` zurück, wenn keiner aktiv ist)      |
| `allow_usage`         | Ob das Team weiterhin Guthaben verbrauchen kann                          |

Jedes Los in `breakdown` hat eine `purchase_kind` von `Subscription`, `Top-up`, `Manual`, `Setup` oder `Pending`.

## Eine Aufladung kaufen

`POST /user/purchase-topup` belastet eine gespeicherte Karte bei Stripe und kauft Guthaben in einem Schritt. Es gibt keine Checkout-Weiterleitung oder eingebettete Zahlungsoberfläche.

Gib die Guthabenmenge im Anfragetext an:

```json theme={null}
{ "credits": 10000 }
```

| Feld      | Beschreibung                     |
| --------- | -------------------------------- |
| `credits` | Anzahl der zu kaufenden Guthaben |

Unterstützte Werte: **10.000**, **20.000**, **80.000** und **100.000**.

Für API-Details siehe [Aufladung kaufen](/api-reference/billing/purchase-topup).

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.olostep.com/user/purchase-topup",
      headers={
          "Authorization": "Bearer <API-TOKEN>",
          "Content-Type": "application/json",
      },
      json={"credits": 10000},
  )
  print(response.status_code)
  print(response.json())
  ```

  ```js Node theme={null}
  const res = await fetch("https://api.olostep.com/user/purchase-topup", {
    method: "POST",
    headers: {
      Authorization: "Bearer <API-TOKEN>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ credits: 10000 }),
  })
  console.log(res.status)
  console.log(await res.json())
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
    -H "Authorization: Bearer <API-TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{"credits": 10000}'
  ```
</CodeGroup>

### Anforderungen

* Das Team muss einen Stripe-Kunden mit mindestens einer gespeicherten Karte haben.
* Pro Team ist nur ein Kaufversuch alle **60 Sekunden** erlaubt. Wenn du die Abkühlzeit erreichst, ist die Antwort **429** mit einem `Retry-After`-Header.

### Antworten

**200** — Zahlung erfolgreich:

```json theme={null}
{
  "success": true,
  "payment_intent_id": "pi_xxx",
  "credits": 10000
}
```

**202** — Zahlung wird noch verarbeitet. Guthaben wird hinzugefügt, sobald Stripe die Zahlung bestätigt:

```json theme={null}
{
  "success": true,
  "status": "processing",
  "payment_intent_id": "pi_xxx",
  "message": "Zahlung wird verarbeitet. Guthaben wird hinzugefügt, sobald die Zahlung bestätigt ist.",
  "credits": 10000
}
```

<Note>
  Guthaben wird durch den Stripe-Webhook nach Zahlungsbestätigung ausgegeben, nicht direkt aus der HTTP-Antwort. Behandle **200** als Zahlungserfolg; frage `GET /user/credits/info` ab, wenn du das aktualisierte Guthaben bestätigen musst.
</Note>

### Häufige Fehler

| Status | Fehler                    | Wann                                                       |
| ------ | ------------------------- | ---------------------------------------------------------- |
| 400    | `missing_topup_selector`  | `credits` wurde nicht gesendet                             |
| 400    | `invalid_credits`         | Guthabenmenge ist nicht in der erlaubten Liste             |
| 400    | `no_stripe_customer`      | Team hat keinen Stripe-Kunden                              |
| 400    | `no_payment_method`       | Keine gespeicherte Karte vorhanden                         |
| 402    | `payment_failed`          | Keine gespeicherte Karte hat die Belastung abgeschlossen   |
| 429    | `purchase_topup_cooldown` | Ein weiterer Kauf wurde innerhalb von 60 Sekunden versucht |
| 503    | `payment_status_unknown`  | Mehrdeutiger Stripe-Fehler; warte vor dem erneuten Versuch |