# Billing

Hooksbase billing is project-scoped and dashboard-first. The current product supports self-serve upgrades for Starter, Pro, and Business, while Free remains unsubscribed and Enterprise stays manual.

## Auth model

- **Dashboard** `session auth`: Billing views, checkout, and provider management open from the [dashboard](/docs/dashboard.md) — go to project settings and open the billing tab.
- **Provider-managed**: The active billing provider is environment-level and can be Stripe or Polar. Both are handled transparently through the dashboard.
- **Public API**: Billing is not exposed as a Public API surface. Use the dashboard for checkout and provider management.

## Plans and self-serve upgrades

Self-serve checkout supports:

- Starter
- Pro
- Business

Billing behavior to know up front:

- Free does not subscribe
- Enterprise remains support-managed
- monthly deliveries are the only metered overage dimension today
- checkout and provider-native management availability depend on the current project state

## Checkout and manage flows

The dashboard billing tab shows:

- the active provider
- the external customer or account linkage
- the plan catalog
- monthly delivery usage
- whether checkout and provider management are currently available for the project

When checkout is available, the dashboard opens a provider checkout page. When the project already has a linked billing account, the dashboard opens the provider's native management portal instead.

Self-serve boundaries matter:

- Starter, Pro, and Business can use checkout when the project is eligible
- Free has no subscription checkout
- Enterprise is manual and support-managed
- provider-managed state is environment-wide and currently resolves through Stripe or Polar

## Usage, overage, and retention

Billing and limits interact in a few important ways:

- overage allowance is part of project state and not available on the free tier
- usage reporting exposes monthly delivery consumption for billing context
- quota enforcement still happens at project and webhook level for ingest rate, backlog depth, replay volume, and storage
- retention windows affect how long payloads remain replayable, even on paid plans

Use [delivery analytics](/docs/delivery-analytics.md) when you need operational usage, backlog, or per-webhook metrics. Billing usage helps answer subscription questions, but it is not the complete quota and observability surface. Use [limits and quotas](/docs/limits.md) for the canonical tier quota table, file limits, replay windows, and feature gates.

## Common mistakes

- Treating billing as a Public API feature instead of a dashboard product flow.
- Assuming every plan change is self-serve. Enterprise remains manual.
- Confusing billing usage with the broader operational quotas enforced elsewhere in the platform.
- Assuming checkout and management links are always available for every current project state.