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

# Metering & billing

> The immutable usage ledger and the billing entities behind credits.

Metering is the cross-cutting backbone — every AI action writes here. See the
concept guide on [metering & credits](/guides/metering-credits) for the flow.

## Metering (`metering` app)

| Model               | Purpose                        | Notes                                                                                                             |
| ------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `UsageEvent`        | One record per AI action       | Immutable. `provider`, `model`, tokens, `credits`, **`cost_usd`** (real cost), `byok` flag. Indexed on (org, ts). |
| `CreditWallet`      | Per-org credit balance         | 1:1 Organization. Tracks `balance` + `reserved`.                                                                  |
| `CreditTransaction` | Ledger entry                   | Immutable. `kind` ∈ `GRANT · TOPUP · SPEND · REFUND`.                                                             |
| `RateCard`          | Per-feature preflight price    | `credits_per_unit`, optional per-model multipliers.                                                               |
| `AICredential`      | Self-host provider key storage | Encrypted; used by the self-host/Community edition, not hosted BYOK.                                              |

## Billing (`billing` app)

| Model          | Purpose                                                                      |
| -------------- | ---------------------------------------------------------------------------- |
| `BillingPlan`  | Subscription tier (price, included monthly credits, limits, Stripe price id) |
| `CreditPack`   | One-time credit top-up (Stripe price id)                                     |
| `Subscription` | Org → plan (status, Stripe subscription id, period)                          |

## Why this is trustworthy

`UsageEvent.cost_usd` records the **real provider cost**, so
`manage.py check_margins` can prove that no feature is billed below cost and audit
gross margin across both LLM and paid-data spend.

<Note>Generated from the `metering` and `billing` app models; re-syncs each iteration.</Note>