Subscriptions, trials, and credits via Stripe
Subscription tiers, free trials, usage-based billing, credit systems, plan upgrades, proration, dunning, and webhook handling. BuildBase includes all of it, backed by Stripe.
Subscription
Day 12 of 14
Your app is an organization in BuildBase. Your users sign in and work inside workspaces - one per team or customer.
You set up
In the console and the SDK
- Your plans, prices and trials, synced to Stripe
- Seat-based or usage-based pricing, in 21 currencies
- A pricing page and checkout, ready-made or your own
Your users get
Inside their workspace
- A free trial that becomes a plan without a second checkout
- Upgrade, downgrade or cancel from their workspace
- An invoice for every charge, kept in their workspace
Billing features
A complete billing system that covers every scenario as your product grows.
Subscription Plans
Tiered subscription plans with versioning. Define pricing, features, limits, and trial periods per plan. Existing subscribers stay on their version until explicitly migrated.
Full Lifecycle Management
Upgrades, downgrades, cancellations, suspensions, and reactivations. Proration calculated automatically. Grace periods enforced. State transitions logged.
Free Trials
Trials convert to paid subscriptions automatically at expiration. Configurable trial duration and optional credit card requirement. Expiration notifications included.
Credit System
Credit packages, promotional grants, and real-time consumption tracking. Credits expire on schedule, balances update instantly, and low-balance alerts fire automatically.
Usage Metering & Quotas
Per-plan limits on any metric: API calls, seats, storage, emails sent. Real-time usage tracking, metered usage sync to Stripe, and automatic overage charges. Quotas reset every month.
Invoicing
Automated invoices for every billing event. Per-workspace invoice history with line items, taxes, and credits tracked per transaction. Downloadable PDF format.
How it works
Define subscription plans in the BuildBase dashboard - name, price, billing interval, included features, and usage limits. Create plan groups for different pricing in different markets.
When a customer subscribes, BuildBase creates the Stripe subscription, provisions the workspace, applies feature flags, sets usage quotas, and starts tracking metered usage. One API call.
When a payment fails, retries follow Stripe's schedule. The customer receives a notification. Webhook events fire to your application. If the payment ultimately fails, the subscription is suspended and workspace features are restricted automatically.
Every billing event - subscription created, upgraded, payment succeeded, trial ending, credit purchased - fires a system event available via webhooks or workflow triggers.
Stripe integration
BuildBase uses Stripe as the payment processor and adds the business logic Stripe leaves to you - plan transitions, proration, dunning, and subscription state management.
- Products and prices synced to Stripe automatically
- Webhook processing for all Stripe events
- Customer lifecycle management
- Checkout session creation and handling
- Subscription state machine with all transitions
- Payment failure handling with retry logic
- Metered usage reporting to Stripe
- Pricing in 21 currencies, with regional plan groups
Hours
To integrate
Most teams spend 2-3 months on billing engineering. Configure plans in the dashboard and start charging in hours.
Full
Revenue visibility
Subscriptions, payments, credits, trials - every billing event is tracked, logged, and available via API.
Automatic
Invoicing
Invoices are generated for every transaction. Per-workspace billing history is always available.
Billing in your code
React hooks for subscriptions, credits, and quotas. Conditional components for paywalls and trial warnings.
import {
useSubscription,
useTrialStatus,
useCreateCheckoutSession,
WhenTrialEnding,
WhenNoSubscription,
WhenSubscriptionToPlans,
} from '@buildbase/sdk/react';
function BillingPage({ workspaceId }) {
const { subscription } = useSubscription(workspaceId);
const { isTrialing, daysRemaining } = useTrialStatus();
const { createCheckoutSession } = useCreateCheckoutSession(workspaceId);
return (
<>
<WhenTrialEnding daysThreshold={3}>
<Banner>{daysRemaining} days left in your trial.</Banner>
</WhenTrialEnding>
<WhenNoSubscription>
<button onClick={() => createCheckoutSession({
planVersionId: 'pro-v1',
billingInterval: 'monthly',
})}>
Subscribe to Pro
</button>
</WhenNoSubscription>
<WhenSubscriptionToPlans plans={['starter']}>
<UpgradePrompt />
</WhenSubscriptionToPlans>
</>
);
}import BuildBase from '@buildbase/sdk';
const bb = BuildBase({ serverUrl, orgId, getSessionId });
// Record usage and check quota
const usage = await bb.usage.record(workspaceId, {
quotaSlug: 'api-calls',
quantity: 1,
});
if (usage.available <= 0) {
return Response.json(
{ error: 'Quota exceeded' },
{ status: 429 }
);
}
// Consume credits
const result = await bb.credits.consume(
workspaceId,
{ amount: 10, description: 'AI generation' }
);Frequently Asked Questions
Do I still need a Stripe account?
Yes. BuildBase handles subscription lifecycle, plan versioning, and metered usage. Stripe processes the payments. Connect your Stripe API keys in the dashboard.
Can I offer free trials without requiring a credit card?
Yes. Each plan version supports configurable trial periods with optional card requirements. Trial-to-paid conversion is handled automatically.
How does usage-based billing work?
Define a limit on your plan (e.g., 1,000 API calls/month) and record usage from your server with one SDK call. Turn on overage for that plan and usage past the limit is billed through Stripe - no billing code required.
What happens when a user exceeds their quota?
Trial users are always capped at the included limit. For paid users it is your choice per plan: with overage on, usage continues and the overage is added to the next Stripe invoice; with it off, usage stops at the limit.
Can I change pricing without affecting existing subscribers?
Yes. Plans are versioned. Existing subscribers stay on their current version. New subscribers get the latest. Migration paths between versions are supported.
Does the credit system work with Stripe?
Credits are purchased via Stripe checkout. The credit ledger, balance tracking, expiration, and consumption are managed by BuildBase. Credits and subscriptions work independently.