# Introduction (https://docs.billwave.example/)

Billwave [#billwave]

Billwave is a billing infrastructure for subscriptions, usage, entitlements,
credits, and seat-based products.

The docs should answer three questions in order:

1. What does Billwave model?
2. How do I represent my pricing correctly?
3. What API calls and lifecycle flows do I use in production?

What you build with Billwave [#what-you-build-with-billwave]

* **Subscription lifecycle** without bespoke webhook code
* **Entitlements** that gate features by plan
* **Usage metering** for API calls, credits, or quotas
* **Entity management** for per-seat, per-project, or per-workspace billing
* **Code-first plans** with an SDK that syncs your definitions with a single command

The three runtime primitives [#the-three-runtime-primitives]

```ts
import { Billwave } from "@digvijay-x1/billwave";

const billwave = new Billwave({ secretKey: process.env.BILLWAVE_SECRET_KEY });

await billwave.attach({
  customer: "user_123",
  product: "pro-monthly",
});

const access = await billwave.check({
  customer: "user_123",
  feature: "api_calls",
});

await billwave.track({
  customer: "user_123",
  feature: "api_calls",
  value: 1,
});
```

Read in this order [#read-in-this-order]

1. Learn the system [#1-learn-the-system]

* [Quickstart](/getting-started/quickstart)
* [How it works](/getting-started/how-it-works)
* [Data model](/getting-started/data-model)
* [Pricing models](/pricing/pricing-models)

2. Model your product [#2-model-your-product]

* [Plans & products](/pricing/plans)
* [Entitlements & features](/pricing/features)
* [Define plans in code](/pricing/programmatic-plans)
* [Included vs usage-based](/pricing/included-vs-usage-based)
* [Package pricing](/pricing/package-pricing)
* [Graduated pricing](/pricing/graduated-pricing)
* [Volume pricing](/pricing/volume-pricing)
* [Overage](/pricing/overage)
* [Credits](/pricing/credits)
* [Entities & seat-based pricing](/pricing/seat-pricing)

3. Run billing in production [#3-run-billing-in-production]

* [Providers](/getting-started/providers)
* [API keys](/getting-started/api-keys)
* [Webhook setup](/getting-started/webhook-setup)
* [Checkout](/subscriptions/checkout)
* [Trials](/subscriptions/trials)
* [Plan switching](/subscriptions/plan-switching)
* [Billing & invoices](/subscriptions/billing)
* [Wallet & saved payment methods](/subscriptions/wallet)

Mental model [#mental-model]

Billwave separates:

* **plans**: what customers subscribe to
* **features**: what customers can use
* **entitlements**: whether access should be allowed
* **usage**: how much was consumed
* **rating**: how billable usage becomes money

That separation is what lets you combine:

* subscriptions
* usage-based pricing
* included quotas with overage
* prepaid credits
* seats and other entity-based capacity

Common product shapes [#common-product-shapes]

* SaaS plan with monthly quota and overage
  Read [Included vs usage-based](/pricing/included-vs-usage-based), then
  [Overage](/pricing/overage)
* Pure pay-as-you-go API
  Read [Included vs usage-based](/pricing/included-vs-usage-based), then
  [Package pricing](/pricing/package-pricing) or
  [Graduated pricing](/pricing/graduated-pricing)
* Seat-based team billing
  Read [Plans & products](/pricing/plans), [Entitlements & features](/pricing/features),
  then [Entities & seat-based pricing](/pricing/seat-pricing)
* Credit wallet or top-ups
  Read [Credits](/pricing/credits) and [Billing & invoices](/subscriptions/billing)

Start with these pages [#start-with-these-pages]

<Cards>
  <Card title="Quickstart" href="/getting-started/quickstart" icon="Zap" />

  <Card title="Pricing Models" href="/pricing/pricing-models" icon="Blend" />

  <Card title="Plans & Products" href="/pricing/plans" icon="Layers" />

  <Card title="Checkout Flow" href="/subscriptions/checkout" icon="CreditCard" />
</Cards>