# API: Guthaben, Lizenzen, Auszahlungen und Rechnungen

_API · 7 Min. Lesezeit · Aktualisiert 2026-10-22 · https://lanachat.ai/guides/de/api-billing/_

LanaChat wird über ein einziges Prepaid-**Guthaben** in US-Dollar abgerechnet: **Lizenzen** (eine pro Telegram-Account, 30 Tage) und eine **Kommission** auf den Nettoumsatz werden davon abgezogen. Sie laden das Guthaben mit Krypto-Einzahlungen auf. Affiliate-Einnahmen können **ausgezahlt** werden. Jeder Billing-Endpoint benötigt ein **owner**-Token: in den Beispielen steht `$LANACHAT_TOKEN` dafür.

## Endpunkte

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/billing/balance` | Das Guthaben, Nettoumsatz und Kommissionsstufe des Monats | `owner` | Planned |
| GET | `/billing/ledger` | Alle Bewegungen: Einzahlungen, Lizenzen, Kommission, Rückerstattungen | `owner` | Planned |
| GET | `/billing/ledger.csv` | Dasselbe Journal als CSV (`from=`, `to=`) | `owner` | Planned |
| GET | `/billing/deposit-addresses` | Eine Einzahlungsadresse pro Chain (mit Memo auf Solana) | `owner` | Planned |
| GET | `/billing/deposits` | Einzahlungen und deren Bestätigungen | `owner` | Planned |
| GET | `/billing/licences` | Lizenzen auf Lager und zugewiesen, mit verbleibenden Tagen | `owner` | Planned |
| POST | `/billing/licences/buy` | Lizenzen kaufen: einzeln oder als Paket mit 10, 25 oder 50 | `owner` | Planned |
| POST | `/billing/licences/assign` | Eine Lizenz aus dem Lager einem Account zuweisen | `owner` | Planned |
| POST | `/billing/licences/unassign` | Lizenz mit Restlaufzeit zurück ins Lager nehmen | `owner` | Planned |
| PATCH | `/billing/licences/auto-renew` | Auto-renew für einen Account aktivieren oder deaktivieren | `owner` | Planned |
| GET | `/billing/withdrawals` | Affiliate-Auszahlungen und deren Status | `owner` | Planned |
| POST | `/billing/withdrawals` | Auszahlung von Affiliate-Einnahmen anfordern (ab $500) | `owner` | Planned |
| GET | `/billing/invoices` | Monatsabrechnungen (`year=`) | `owner` | Planned |
| GET | `/billing/invoices/{id}.pdf` | Einzelne Abrechnung als PDF | `owner` | Planned |
| PUT | `/billing/details` | Firmenname, Adresse und USt-Nummer auf Abrechnungen | `owner` | Planned |

## Preise in einer Tabelle

| What | Price |
|---|---|
| Eine Lizenz (ein Telegram-Account, 30 Tage) | $19 |
| Paket mit 10 Lizenzen | $170 |
| Paket mit 25 Lizenzen | $375 |
| Paket mit 50 Lizenzen | $650 |
| Kommission bis $30k Nettoumsatz im Monat | 12% der AI-Umsätze, 4% der manuellen Umsätze |
| Kommission von $30k bis $100k | 10% und 3% |
| Kommission über $100k | 8% und 2% |

Gezählt wird der Nettoumsatz des gesamten Workspaces im Kalendermonat; am 1. wird zurückgesetzt. Telegram Stars zählen mit $0.013 pro Stück zum Nettoumsatz.

## Das balance-Objekt

```json
{
  "balance_cents": 48210,
  "month": "2026-10",
  "net_sales_cents": 1870400,
  "tier": { "up_to_cents": 3000000, "ai_rate_bp": 1200, "manual_rate_bp": 300 },
  "licences": { "in_stock": 4, "assigned": 11, "expiring_7d": 2 },
  "low_balance": false
}
```

| Field | Type | Description |
|---|---|---|
| `balance_cents` | integer | Prepaid-Guthaben, in US-Cent |
| `month` | string | Der gezählte Kalendermonat, `YYYY-MM` |
| `net_sales_cents` | integer | Nettoumsatz des Workspaces in diesem Monat |
| `tier` | object | Die aktuelle Stufe: Grenze `up_to_cents`, AI- und manueller Satz in Basispunkten |
| `licences` | object | Lizenzen `in_stock`, `assigned` und zugewiesene, die in 7 Tagen enden (`expiring_7d`) |
| `low_balance` | boolean | `true`, wenn das Guthaben die nächsten 7 Tage Lizenzen nicht deckt |

Sätze sind in Basispunkten: `1200` entspricht 12%.

## Das ledger entry-Objekt

Jede Zeile von **Billing › Activity** in der Console.

```json
{
  "id": "led_90211",
  "at": "2026-10-06T14:40:00Z",
  "kind": "licences",
  "label": "Licences · pack of 10",
  "amount_cents": -17000,
  "balance_after_cents": 31210
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Die Zeile |
| `at` | string | ISO 8601, UTC |
| `kind` | string | `deposit`, `licences`, `commission`, `refund`, `affiliate` oder `other` |
| `label` | string | Der Text der Zeile, wie in der Console |
| `amount_cents` | integer | Positiv bei Geldeingang, negativ bei Abgang |
| `balance_after_cents` | integer | Guthaben nach dieser Zeile |

Eine `commission`-Zeile gehört zu einem Verkauf: Die Console zeigt den Fan, die Stufe, wer das Angebot gesendet hat (AI oder manuell), wie der Netto berechnet wurde ("12,500 ★ × $0.013") und den Satz.

## Das deposit-Objekt

```json
{
  "id": "dep_4",
  "at": "2026-10-06T13:52:00Z",
  "chain": "usdt-tron",
  "sent_cents": 100000,
  "fee_cents": 1000,
  "credited_cents": 99000,
  "status": "pending",
  "confirmations": "12/19"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Die Einzahlung |
| `at` | string | Zeitpunkt, ISO 8601 |
| `chain` | string | `usdc-eth`, `usdc-sol`, `usdt-sol`, `usdt-tron` oder `usdt-eth` |
| `sent_cents`, `fee_cents`, `credited_cents` | integer | Gesendet, Gebühr, Gutschrift auf Guthaben |
| `status` | string | `pending` dann `confirmed` |
| `confirmations` | string | Netzwerkbestätigungen gezählt, solange pending |

USDC auf Ethereum wird 1:1 ohne Gebühr gutgeschrieben. Jede andere Chain hat 1% Gebühr: Die Einzahlung wird bei Ankunft in USDC (ERC20) umgewandelt. Das Minimum pro Aufladung beträgt $25.

## Das licence-Objekt

```json
{
  "account_id": "acc_1001",
  "creator_id": "cr_lea",
  "days_left": 18,
  "expires_at": "2026-10-24T09:00:00Z",
  "auto_renew": true
}
```

| Field | Type | Description |
|---|---|---|
| `account_id` | string | Der Telegram-Account, auf dem die Lizenz läuft |
| `creator_id` | string | Ihre Creatorin |
| `days_left` | integer | Verbleibende Tage, von 30 |
| `expires_at` | string | Enddatum |
| `auto_renew` | boolean | Bei Ablauf automatisch aus Lager (oder einzeln kaufen) verlängern |

Lizenzen im Lager werden gezählt, nicht einzeln gelistet: Jede behält ihre Resttage (30 bei neuer Lizenz).

## Das withdrawal-Objekt

```json
{ "id": "wd_118", "status": "pending_review", "amount_cents": 50000, "requested_at": "2026-10-06T15:00:00Z", "tx_hash": null }
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Die Auszahlung |
| `status` | string | `pending_review`, `sent` (mit `tx_hash`) oder `rejected` mit Grund |
| `amount_cents` | integer | Angeforderter Betrag, mindestens 50000 ($500) |
| `requested_at` | string | ISO 8601, UTC |
| `tx_hash` | string or null | Die Transaktion, sobald gesendet |

## Das invoice-Objekt

```json
{
  "id": "LC-2026-09",
  "month": "2026-09",
  "licences_cents": 22800,
  "commission_cents": 930000,
  "total_cents": 952800,
  "status": "paid",
  "pdf_url": "https://api.lanachat.ai/v1/billing/invoices/LC-2026-09.pdf"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Rechnungsnummer, `LC-YYYY-MM` |
| `month` | string | Abgedeckter Monat |
| `licences_cents`, `commission_cents`, `total_cents` | integer | Lizenzen, Kommission und Gesamtbetrag des Monats |
| `status` | string | Bezahlt, in Bearbeitung (aktueller Monat) oder fehlgeschlagen |
| `pdf_url` | string | PDF der Abrechnung |

## Guthaben und Journal

### Guthaben abfragen

`GET /billing/balance` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/balance \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Die Antwort ist das balance object.

### Journal auflisten

`GET /billing/ledger` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from`, `to` | string | No | Tage `YYYY-MM-DD`, UTC, beide inklusive |
| `limit`, `cursor` | number, string | No | [Pagination](https://lanachat.ai/guides/de/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/billing/ledger?from=2026-10-01&to=2026-10-06" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "led_90211", "at": "2026-10-06T14:40:00Z", "kind": "licences", "label": "Licences · pack of 10", "amount_cents": -17000, "balance_after_cents": 31210 },
    { "id": "led_90207", "at": "2026-10-06T13:20:00Z", "kind": "commission", "label": "Lea · Marco", "amount_cents": -468, "balance_after_cents": 48210 },
    { "id": "led_90150", "at": "2026-10-05T09:02:00Z", "kind": "deposit", "label": "Deposit · USDC on Ethereum", "amount_cents": 300000, "balance_after_cents": 48678 }
  ],
  "next_cursor": "eyJpZCI6ImxlZF85MDE0OSJ9"
}
```

### Journal als CSV exportieren

`GET /billing/ledger.csv` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from`, `to` | string | No | Tage `YYYY-MM-DD`, UTC |

```bash
curl "https://api.lanachat.ai/v1/billing/ledger.csv?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $LANACHAT_TOKEN" -o ledger-2026-09.csv
```

Dieselben Zeilen wie **Export CSV** in **Billing › Activity**, bereit für Ihre Buchhaltung.

## Einzahlungen

### Einzahlungsadressen abrufen

`GET /billing/deposit-addresses` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/deposit-addresses \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Die Antwort gibt eine Adresse pro Chain (Ethereum, Solana, Tron) und für Solana das Memo.

> Warning: Auf Solana kann eine Einzahlung ohne Memo nicht Ihrem Workspace zugeordnet werden. Senden Sie immer sowohl Adresse als auch Memo.

Sie können USDC auf Ethereum (ERC20), USDC auf Solana, USDT auf Solana, USDT auf Tron (TRC20) oder USDT auf Ethereum (ERC20) senden. Die Netzwerkgebühr Ihrer Überweisung wird von Ihrer Wallet bezahlt.

### Einzahlungen auflisten

`GET /billing/deposits` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/deposits \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "dep_4", "at": "2026-10-06T13:52:00Z", "chain": "usdt-tron", "sent_cents": 100000, "fee_cents": 1000, "credited_cents": 99000, "status": "pending", "confirmations": "12/19" },
    { "id": "dep_3", "at": "2026-10-05T09:02:00Z", "chain": "usdc-eth", "sent_cents": 300000, "fee_cents": 0, "credited_cents": 300000, "status": "confirmed", "confirmations": null }
  ],
  "next_cursor": null
}
```

Das Guthaben wird automatisch gutgeschrieben, sobald eine Einzahlung `confirmed` ist; dann erscheint sie auch als `deposit`-Zeile im Journal.

## Lizenzen

### Lizenzen auflisten

`GET /billing/licences` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/licences \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Die Antwort enthält die Lizenzen im Lager und je ein licence object pro zugewiesenem Account mit Restlaufzeit.

### Lizenzen kaufen

`POST /billing/licences/buy` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pack` | integer | Yes | `1` (einzeln, $19), `10` ($170), `25` ($375) oder `50` ($650) |
| `qty` | integer | Yes | Anzahl dieses Pakets |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/buy \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"pack": 10, "qty": 1}'
```

```json
{ "licences_added": 10, "amount_cents": 17000, "balance_cents": 31210, "ledger_id": "led_90211" }
```

Die Lizenzen gehen sofort in Ihr Lager. Bei zu geringem Guthaben kommt `402` (`insufficient_balance`). Lizenzen im Lager verfallen nie, gekaufte Lizenzen sind nicht erstattbar.

### Lizenz zuweisen

`POST /billing/licences/assign` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | Der Telegram-Account, der eine Lizenz erhält |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/assign \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001"}'
```

Die Antwort ist das licence object des Accounts. Die Lagerlizenz mit den wenigsten Resttagen wird zuerst verwendet: deren Resttage oder 30 Tage, wenn sie neu ist. Auto-renew ist standardmäßig aktiviert.

### Lizenz zurücknehmen

`POST /billing/licences/unassign` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | Der Account, der seine Lizenz zurückgibt |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/unassign \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001"}'
```

Die Lizenz geht mit ihren Resttagen zurück ins Lager. Die AI antwortet auf diesem Account sofort nicht mehr. Um eine Lizenz zu einem anderen Account zu verschieben, nehmen Sie sie zurück und weisen sie dann neu zu: Die Resttage bleiben, kostenlos.

### Auto-renew aktivieren oder deaktivieren

`PATCH /billing/licences/auto-renew` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | string | Yes | Der Account |
| `auto_renew` | boolean | Yes | `true` für automatische Verlängerung bei Ablauf |

```bash
curl -X PATCH https://api.lanachat.ai/v1/billing/licences/auto-renew \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "acc_1001", "auto_renew": false}'
```

Wenn die Tage ablaufen, nimmt Auto-renew zuerst eine Lizenz aus dem Lager oder kauft eine einzelne Lizenz ($19), falls das Lager leer ist. Es kann nicht ohne Guthaben kaufen: Beobachten Sie `low_balance` oder den `billing.low_balance` [webhook](https://lanachat.ai/guides/de/api-webhooks/).

## Affiliate-Auszahlungen

### Auszahlungen auflisten

`GET /billing/withdrawals` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/withdrawals \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Eine Liste von withdrawal objects, neueste zuerst.

### Auszahlung anfordern

`POST /billing/withdrawals` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `amount_cents` | integer | Yes | Mindestens 50000 ($500), maximal was verfügbar ist |

```bash
curl -X POST https://api.lanachat.ai/v1/billing/withdrawals \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 50000}'
```

```json
{ "id": "wd_118", "status": "pending_review", "amount_cents": 50000, "requested_at": "2026-10-06T15:00:00Z", "tx_hash": null }
```

Die Einnahmen werden in USDC an die hinterlegte Wallet gesendet, 7 Tage nach Monatsende. Es können nur Affiliate-Einnahmen ausgezahlt werden, niemals das Prepaid-Guthaben. Eine Anfrage unter $500 wird abgelehnt.

## Abrechnungen

### Abrechnungen auflisten

`GET /billing/invoices` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `year` | integer | No | Zum Beispiel `2026` |

```bash
curl "https://api.lanachat.ai/v1/billing/invoices?year=2026" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Eine invoice object pro Monat.

### Abrechnung herunterladen

`GET /billing/invoices/{id}.pdf` · `owner`

```bash
curl https://api.lanachat.ai/v1/billing/invoices/LC-2026-09.pdf \
  -H "Authorization: Bearer $LANACHAT_TOKEN" -o LC-2026-09.pdf
```

> Warning: Prüfen Sie Ihre Abrechnungen. Ein Abrechnungsfehler muss innerhalb von 60 Tagen nach der Abrechnung gemeldet werden, auf der er erscheint; danach ist die Abrechnung endgültig.

### Rechnungsdetails setzen

`PUT /billing/details` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company` | string | No | Firmenname |
| `email` | string | No | Rechnungs-E-Mail |
| `address`, `city`, `postal`, `country` | string | No | Postadresse |
| `vat` | string | No | USt-Nummer |

```bash
curl -X PUT https://api.lanachat.ai/v1/billing/details \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"company": "Mia Agency Ltd", "email": "billing@mia-agency.com", "address": "12 Market Street", "city": "Dublin", "postal": "D02 X285", "country": "IE", "vat": "IE1234567T"}'
```

Dieselben Felder wie **Billing › Billing details**. Abrechnungen enthalten diese Angaben. `PUT` ersetzt alle: Ein Feld, das Sie weglassen, wird geleert.

## Verwandte Artikel

- [LanaChat API: Schnellstart, Authentifizierung und Fehler](https://lanachat.ai/guides/de/api-overview/)
- [Abrechnung: Lizenzen, Provision und Guthaben](https://lanachat.ai/guides/de/billing/)