Quickstart
Getting Started
Install Billing SDK and create your first billing integration in 5 minutes.
1. Install
Pick your package manager and install the core package plus the provider adapter of your choice.
npm install billingsdk-core billingsdk-stripe
2. Define your plans
Declare your pricing plans, features, and entitlements in a single configuration object.
import { definePlans } from "billingsdk-core";
export const plans = definePlans({
free: {
name: "Free",
prices: [],
features: {
ai_generations: { limit: 10, reset: "month" },
team_members: { limit: 1 },
custom_domain: false,
},
},
pro: {
name: "Pro",
prices: [
{ id: "pro-monthly", amount: 2000, currency: "usd", interval: "month" },
],
features: {
ai_generations: { limit: 1000, reset: "month" },
team_members: { limit: 5 },
custom_domain: true,
},
},
});
3. Create billing client
Pass your adapter and plans to createBilling. The same interface works for every provider.
import { createBilling } from "billingsdk-core";
import { stripe } from "billingsdk-stripe";
import { plans } from "./plans";
export const billing = createBilling({
adapter: stripe({ secretKey: process.env.STRIPE_SECRET_KEY! }),
plans,
});
4. Create a checkout
Generate a checkout session with a single function call. Redirect your user to the returned URL.
const checkout = await billing.checkout.create({
plan: "pro",
customer: { email: "user@example.com" },
successUrl: "https://example.com/dashboard",
cancelUrl: "https://example.com/pricing",
});
// Redirect user to checkout.url
5. Check entitlements
Gate features behind plan entitlements. Metered features return remaining usage, boolean features return allowed status.
const { allowed, remaining } = await billing.entitlements.check({
customerId: "cus_123",
feature: "ai_generations",
});
if (!allowed) {
return res.status(403).json({ error: "Upgrade required" });
}
6. Handle webhooks
Verify and handle normalized webhook events from any provider. One event shape, every provider.
const event = await billing.webhooks.verify({
body: request.body,
headers: request.headers,
});
switch (event.type) {
case "subscription.created":
await db.users.activate({ subscriptionId: event.data.id });
break;
case "subscription.cancelled":
await db.users.deactivate({ subscriptionId: event.data.id });
break;
}