> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing SDK
> Add pricing tables, subscription management, and usage meters to your app, and generate Dodo Payments API routes with the open-source Billing SDK CLI.
Billing SDK is an open-source set of React billing components, with a CLI that connects your project to Dodo Payments. The CLI generates the API routes, React hook, and Dodo Payments client for your framework, and adds components such as pricing tables and usage meters.
## Overview
Billing SDK includes:
* **React Components**: Pre-built, customizable billing components for React applications.
* **CLI Tooling**: A command-line interface that initializes projects and adds components.
* **Framework Support**: Templates for Next.js, Express.js, Hono, Fastify, NestJS, and React.
* **Payment Provider**: Full integration with Dodo Payments.
## Quick Start
To set up Billing SDK in an existing project, run the CLI from the project root:
Run the CLI with `npx`, without installing it:
```bash theme={null}
npx @billingsdk/cli --help
```
Or install it globally for frequent use. The global install adds the `billingsdk` command, for example `billingsdk init`:
```bash theme={null}
npm install -g @billingsdk/cli
```
Run the interactive setup to add billing to your project:
```bash theme={null}
npx @billingsdk/cli init
```
The CLI prompts you to select:
* Your framework: Next.js, Express.js, React, Hono, Fastify, or NestJS. The CLI detects your framework and marks it as detected.
* Your payment provider: select **Dodo Payments**.
Add individual billing components to your project:
```bash theme={null}
npx @billingsdk/cli add pricing-table-one
npx @billingsdk/cli add subscription-management
```
## Supported Frameworks
Billing SDK has a Dodo Payments template for each of these frameworks:
| Framework | Dodo Payments |
| - | - |
| Next.js | Yes |
| Express.js | Yes |
| Hono | Yes |
| React | Yes |
| Fastify | Yes |
| NestJS | Yes |
## CLI Commands
### `@billingsdk/cli init`
`init` sets up billing in your project: it installs the framework template with the Dodo Payments integration, and the dependencies that the template needs.
**What it does:**
1. **Framework Selection**: You choose your framework and payment provider.
2. **Template Installation**: The CLI downloads the template for your framework and provider from the Billing SDK registry, and installs its files.
3. **Dependency Management**: The CLI installs the template's dependencies, such as `dodopayments`, `standardwebhooks`, and `zod`, with npm, pnpm, Yarn, or Bun.
4. **File Generation**: The CLI writes the configuration files and boilerplate code. For Express.js, Fastify, Hono, and NestJS, it writes them under `src/`.
**Example:**
```bash theme={null}
npx @billingsdk/cli init
```
To run `init` without prompts, pass `--framework`, `--provider`, and `--yes`, for example `npx @billingsdk/cli init --framework nextjs --provider dodopayments --yes`. Add `--dry-run` to list the files without writing them, `--no-install` to skip the dependency install, or `--package-manager` to choose `npm`, `pnpm`, `yarn`, or `bun`.
### `@billingsdk/cli add`
`add` installs one billing component in your project through the shadcn/ui registry system. It runs `shadcn@latest add @billingsdk/` with your package manager's runner.
**Examples:**
```bash theme={null}
# Add a pricing table
npx @billingsdk/cli add pricing-table-one
# Add subscription management
npx @billingsdk/cli add subscription-management
# Add usage monitoring
npx @billingsdk/cli add usage-meter-circle
```
**What happens:**
1. The `shadcn` CLI downloads the component configuration from the registry.
2. It installs the component files in your `components/billingsdk/` directory.
3. It updates your project configuration if needed.
4. It installs any additional dependencies.
## Generated Files Structure
After you run `init`, your project contains:
* **API Routes**: Endpoints for checkout, customers, customer payments, products, subscriptions, and webhooks. The React template has no API routes.
* **Hooks**: A `useBilling` React hook for billing operations, for React and Next.js.
* **Library Files**: The Dodo Payments client setup and helper functions, in `lib/dodopayments.ts`.
* **Environment Configuration**: An example environment file, `.env.example`.
### Next.js Example Structure
For Next.js, `init` writes these files:
```text theme={null}
your-project/
├── app/api/
│ ├── checkout/route.ts
│ ├── customer/route.ts
│ ├── customer/payments/route.ts
│ ├── customer/subscriptions/route.ts
│ ├── product/route.ts
│ ├── products/route.ts
│ └── webhook/route.ts
├── hooks/
│ └── useBilling.ts
├── lib/
│ └── dodopayments.ts
└── .env.example
```
## Environment Configuration
After initialization, set your environment variables. Get the API key from **Developer → API Keys** and the webhook key from **Developer → Webhooks** in the dashboard:
```bash theme={null}
# DodoPayments
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here
# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
```
Set `DODO_PAYMENTS_ENVIRONMENT` to `test_mode` or `live_mode`. The generated Dodo Payments client throws an error for any other value.
Store your API keys in environment variables. Never commit them to version control.
## Available Components
Billing SDK provides React components in these groups:
* **Pricing Tables**: Eight variants, `pricing-table-one` through `pricing-table-eight`, for displaying product pricing.
* **Subscription Management**: `subscription-management`, plus cards and dialogs to cancel a subscription or update a plan.
* **Usage Monitoring**: Circular and linear usage meters, and usage tables for usage-based billing.
* **Checkout Components**: A payment method selector, payment details forms, and a payment failure card.
* **Customer Portal**: Billing settings, a billing screen, invoice history, and upcoming charges, for customer self-service.
To browse every component with a live preview, see the [component library](https://billingsdk.com/docs/components).
## Open Source
Billing SDK is open source:
* **Transparency**: You can read how every component works.
* **Community**: Developers build it for other developers.
* **Security**: Anyone can review the code for security issues.
* **Innovation**: Community contributions speed up development.
Billing SDK is released under the GNU General Public License v3.0 (GPL-3.0), which keeps the project open and free.
## Getting Help
For help with Billing SDK, use these resources:
* **GitHub Issues**: [Open an issue](https://github.com/dodopayments/billingsdk/issues)
* **Documentation**: Visit [billingsdk.com/docs](https://billingsdk.com/docs)
* **LLMs Full Documentation**: [billingsdk.com/llms-full.txt](https://billingsdk.com/llms-full.txt)
## Contributing
Billing SDK welcomes contributions. The [contribution guide](https://billingsdk.com/docs/contribution-open-source) explains how to:
* Report bugs
* Request features
* Submit pull requests
* Add new components
* Improve documentation
## Learn More
Complete guide to Billing SDK with examples and best practices
Detailed CLI documentation for all commands and options
Browse all available components with live examples
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.