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

• 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

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

1. Learn the system

• Quickstart
• How it works
• Data model
• Pricing models

2. Model your product

• Plans & products
• Entitlements & features
• Define plans in code
• Included vs usage-based
• Package pricing
• Graduated pricing
• Volume pricing
• Overage
• Credits
• Entities & seat-based pricing

3. Run billing in production

• Providers
• API keys
• Webhook setup
• Checkout
• Trials
• Plan switching
• Billing & invoices
• Wallet & saved payment methods

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

• SaaS plan with monthly quota and overage Read Included vs usage-based, then Overage
• Pure pay-as-you-go API Read Included vs usage-based, then Package pricing or Graduated pricing
• Seat-based team billing Read Plans & products, Entitlements & features, then Entities & seat-based pricing
• Credit wallet or top-ups Read Credits and Billing & invoices

Start with these pages