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

# Analytics & Reporting

Understand usage, revenue, and profit at a glance. The dashboard provides a real‑time ledger of every financial event, user‑level insights, and charts that help you track growth and margins.

## What you can see

* Ledger: every top‑up, charge, refund, and adjustment, with links back to the originating request/user.
* Charts: revenue, provider cost, and profit over time; usage by model; top users and cohorts.
* Users: active users, balances, total spend, last activity, and status - authorized/connected (Coming soon).

## Ledger

Each row represents a financial event.

* Types: deposit (top‑up), charge (usage), withdrawal.
* Core fields: id, timestamp, user, paywall, amount, status.
* Metering: prompt\_tokens, completion\_tokens, total\_tokens (when applicable).
* Costs: provider\_cost (COGS) and platform\_fees (when applicable) to compute profit.
* Metadata: optional JSON for reconciliation (e.g., Stripe payment\_intent, checkout\_session, your internal ids).

Tips

* Use consistent user ids; prefer stable, pseudonymous identifiers.
* Include a requestId in your app and pass it in metadata for safe retries and auditing.
* For manual one‑off charges, record business context in metadata for downstream analytics.

See also:

* [Paywalls, Wallets, Ledger](core-concepts/paywalls-wallets-ledger)
* [Pricing, Metering](core-concepts/pricing-metering)

## Users view (soon)

* Summary per user: total spend, current balance, last activity, and authorization status.
* Drill‑down: per‑user ledger with filters by date, model, and event type.
* Actions: copy authorization/top‑up links for support, review recent errors, and validate connection.

## Charts & KPIs

Track trends and health of your monetization.

* Revenue: sum of usage charges for the selected period.
* Provider cost (COGS): cost of model usage at provider rates.
* Profit: revenue minus provider cost (and any applicable platform fees).
* Users: active payers, new payers, ARPU in period (soon).

<Note>
  In streaming requests, final token counts settle at the end of the stream.
</Note>

## Filtering & segmentation (soon)

Use filters across all views to answer precise questions:

* Time: today, 7/30/90 days, custom dates, and compare periods.
* Model: e.g., `openai/gpt-4o-mini` vs `anthropic/claude-3.5`.
* User attributes: id, status (authorized), high/low balance, new vs returning.
* Event type: deposits, charges, etc.

Common questions you can answer

* Which models drive most revenue and profit this month?
* Who are my top spending users and what is their average cost to serve?
* How many active payers do I have and what is my ARPU?

## Reconciliation (Stripe & custom rails)

<Tabs>
  <Tab title="Default mode">
    Stripe top‑ups appear as deposits in the ledger. We recommend storing payment\_intent or checkout\_session in metadata for each deposit to reconcile with Stripe reports.

    Your own checkout. After payment success, call `POST /v1/user/balance/deposit` and include your payment id in metadata. Use idempotency for safe retries.
  </Tab>

  <Tab title="Shared mode">
    Hosted top‑ups are managed by Paywalls. Your developer earnings accrue from charges. Use the ledger to reconcile earnings and withdrawals.
  </Tab>
</Tabs>

**Operational tips**

* Always log `user`, `requestId`, and ledger `id` in your app logs for easy cross‑reference.
* Make webhook handlers idempotent and respond only after durable writes.

## Export & integrations

* CSV export: Coming soon (download from Ledger and Users views, with column selection and date range).
* Programmatic export: Coming soon (API access for pulling ledger slices into your warehouse).