# Billing

Hangar combines a flat monthly subscription with pay-as-you-go LLM
tokens out of a wallet. The wallet is dollar-precise and atomic.

## Subscription

Subscriptions cover the runtime instance (Fly Machine), channel
routing, skill execution, persistence, and observability.

- Tiers are listed at [/pricing](/pricing) and the machine-readable copy
  at [/pricing.md](/pricing.md).
- The provider is configurable: Stripe (default), LemonSqueezy, or
  Polar. Adapters live under `lib/billing/`.
- Cancellation is **at period end** — you keep access until the
  current cycle ends.

## Wallet

LLM token usage is billed pay-as-you-go from a wallet:

- Every account starts with a small wallet credit on signup.
- Top up at `POST /api/wallet/topup` (or via the dashboard). The body
  is `{ "amountCents": 1000 }` for $10. The response is a hosted
  checkout URL.
- Charges are atomic cents-precision deductions. The `/api/llm/proxy`
  handler debits the wallet **before** calling the upstream provider,
  refunds on failure, and writes a row to `wallet_transactions` with
  the model, prompt-tokens, completion-tokens, and the resolved
  provider cost.
- We do **not** mark up provider tokens. The wallet pays exactly what
  OpenAI / Anthropic / Google / OpenRouter charge.

## Wallet semantics

- Wallet hits zero ⇒ `/api/llm/proxy` returns `402 wallet-empty`.
  No call is made upstream.
- Top-up amount lands in the wallet on the billing webhook, not when
  the user clicks "pay". A delayed webhook means a delayed credit.
- Wallet balance is **fully refundable** on cancellation — email
  support and we credit the original payment method.

## Programmatic top-ups

```bash
curl -X POST https://hangar.so/api/wallet/topup \
  -H "Authorization: Bearer oss_..." \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 1000}'
```

Response:

```json
{
  "url": "https://checkout.stripe.com/..."
}
```

The user opens the URL to complete the payment. Hangar never sees card
details — Stripe / LemonSqueezy / Polar handle the form, we get the
webhook.

## Refunds

- Subscription refunds: prorated for the unused portion of the current
  period on cancellation.
- Wallet refunds: full balance, unconditional, by request via support
  email.
- Provider chargebacks: handled by the billing provider per their
  policy. Hangar reverses the credited wallet amount on receipt of a
  chargeback webhook.