Billing SDK

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:

Install the CLI

Run the CLI with npx, without installing it:

npx @billingsdk/cli --help

Or install it globally for frequent use. The global install adds the billingsdk command, for example billingsdk init:

npm install -g @billingsdk/cli

Initialize a Project

Run the interactive setup to add billing to your project:

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 Components

Add individual billing components to your project:

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:

Framework Selection: You choose your framework and payment provider.
Template Installation: The CLI downloads the template for your framework and provider from the Billing SDK registry, and installs its files.
Dependency Management: The CLI installs the template’s dependencies, such as dodopayments, standardwebhooks, and zod, with npm, pnpm, Yarn, or Bun.
File Generation: The CLI writes the configuration files and boilerplate code. For Express.js, Fastify, Hono, and NestJS, it writes them under src/.

Example:

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/<component> with your package manager’s runner. Examples:

# 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:

The shadcn CLI downloads the component configuration from the registry.
It installs the component files in your components/billingsdk/ directory.
It updates your project configuration if needed.
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:

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:

# 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.

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
Documentation: Visit billingsdk.com/docs
LLMs Full Documentation: billingsdk.com/llms-full.txt

Contributing

Billing SDK welcomes contributions. The contribution guide explains how to:

Report bugs
Request features
Submit pull requests
Add new components
Improve documentation

Learn More

Full Documentation

Complete guide to Billing SDK with examples and best practices

CLI Reference

Detailed CLI documentation for all commands and options

Component Library

Browse all available components with live examples

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Overview

Quick Start

Supported Frameworks

CLI Commands

`@billingsdk/cli init`

`@billingsdk/cli add`

Generated Files Structure

Next.js Example Structure

Environment Configuration

Available Components

Open Source

Getting Help

Contributing

Learn More

Full Documentation

CLI Reference

Component Library

​Overview

​Quick Start

​Supported Frameworks

​CLI Commands

​@billingsdk/cli init

​@billingsdk/cli add

​Generated Files Structure

​Next.js Example Structure

​Environment Configuration

​Available Components

​Open Source

​Getting Help

​Contributing

​Learn More

Full Documentation

CLI Reference

Component Library

Overview

Quick Start

Supported Frameworks

CLI Commands

`@billingsdk/cli init`

`@billingsdk/cli add`

Generated Files Structure

Next.js Example Structure

Environment Configuration

Available Components

Open Source

Getting Help

Contributing

Learn More