Usage billing system for the Veritas B2B API.
Overview#
This package provides a complete billing solution including:
- Pricing tiers (Free, Basic, Pro, Enterprise)
- Usage tracking and metering
- Invoice generation
- Stripe integration for payment processing
- Self-service billing portal
Installation#
bash
pnpm add @veritas/billing
Quick Start#
typescript
import {
createSubscriptionManager,
createUsageTracker,
createInvoiceManager,
getPricingTier,
} from '@veritas/billing';
// Create billing services
const subscriptionManager = createSubscriptionManager({
stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
defaultCurrency: 'usd',
taxRatePercent: 0,
trialPeriodDays: 14,
gracePeriodDays: 7,
});
const usageTracker = createUsageTracker();
const invoiceManager = createInvoiceManager();
// Create a customer
const customer = await subscriptionManager.createCustomer({
apiKeyId: 'key_123',
email: 'dev@example.com',
tier: 'basic',
});
Pricing Tiers#
| Tier | Monthly Price | Included Requests | Rate Limit |
|---|---|---|---|
| Free | $0 | 1,000 | 20/min |
| Basic | $49 | 10,000 | 100/min |
| Pro | $199 | 100,000 | 500/min |
| Enterprise | Custom | Custom | Custom |
Getting Tier Configuration#
typescript
import { getPricingTier, getVisibleTiers, formatPrice } from '@veritas/billing';
// Get a specific tier
const proTier = getPricingTier('pro');
console.log(proTier.includedRequests); // 100000
// Get all visible tiers for pricing page
const tiers = getVisibleTiers();
// Format prices
console.log(formatPrice(19900, 'usd')); // '$199.00'
Tier Recommendations#
typescript
import { recommendTier, getNextTierUp } from '@veritas/billing';
// Recommend tier based on usage
const recommended = recommendTier(50000); // 'pro'
// Get next tier up
const nextTier = getNextTierUp('basic'); // 'pro'
Usage Tracking#
Track API usage in real-time for billing:
typescript
import { createUsageTracker } from '@veritas/billing';
const tracker = createUsageTracker();
// Record API request
await tracker.recordRequest({
customerId: customer.id,
apiKeyId: customer.apiKeyId,
endpoint: 'feed.list',
statusCode: 200,
responseTimeMs: 150,
dataTransferBytes: 5000,
});
// Get usage summary
const summary = await tracker.getUsageSummary(customer);
console.log('Total requests:', summary.totalRequests);
console.log('Overage requests:', summary.overageRequests);
console.log('Estimated overage charges:', summary.estimatedOverageChargeCents);
// Check overage status
const isOverage = await tracker.isInOverage(customer);
const usagePercent = await tracker.getUsagePercentage(customer);
Usage Alerts#
Set up alerts when usage thresholds are reached:
typescript
import { createUsageAlertManager } from '@veritas/billing';
const alertManager = createUsageAlertManager();
// Create alert at 80% usage
alertManager.createAlert({
customerId: customer.id,
thresholdPercent: 80,
enabled: true,
notifyEmail: 'billing@example.com',
notifyWebhook: true,
});
// Check and trigger alerts
await alertManager.checkAlerts(customerId, usagePercent, async (alert) => {
// Send notification
console.log(`Alert triggered: ${alert.thresholdPercent}% usage reached`);
});
Invoice Management#
Create and manage invoices:
typescript
import { createInvoiceManager } from '@veritas/billing';
const invoiceManager = createInvoiceManager({
invoicePrefix: 'INV',
taxRatePercent: 0,
});
// Create invoice
const invoice = await invoiceManager.createInvoice(customer, usageSummary, {
dueInDays: 30,
});
// Finalize and send
await invoiceManager.finalizeInvoice(invoice.id);
// Record payment
await invoiceManager.markPaid(invoice.id);
// Or partial payment
await invoiceManager.recordPayment(invoice.id, 5000);
// Add credit
await invoiceManager.addCredit(invoice.id, 1000, 'Promotional credit');
// Void invoice
await invoiceManager.voidInvoice(invoice.id);
// Get customer invoices
const invoices = await invoiceManager.getCustomerInvoices(customer.id);
// Get overdue invoices
const overdue = await invoiceManager.getOverdueInvoices();
Subscription Management#
Full subscription lifecycle management with Stripe:
typescript
import { createSubscriptionManager } from '@veritas/billing';
const manager = createSubscriptionManager({
stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
defaultCurrency: 'usd',
taxRatePercent: 0,
trialPeriodDays: 14,
gracePeriodDays: 7,
});
// Create customer with subscription
const customer = await manager.createCustomer({
apiKeyId: 'key_123',
email: 'dev@example.com',
companyName: 'Acme Inc',
tier: 'pro',
billingInterval: 'monthly',
});
// Preview tier change
const preview = await manager.previewTierChange(customer.id, 'enterprise');
console.log('Net amount:', preview.netAmountCents);
// Change tier
await manager.changeTier(customer.id, 'enterprise', { immediate: true });
// Cancel subscription
await manager.cancelSubscription(customer.id, {
immediate: false, // Cancel at period end
reason: 'Customer requested',
});
// Reactivate
await manager.reactivateSubscription(customer.id);
Self-Service Portal#
Create Stripe customer portal sessions:
typescript
// Create portal session
const portal = await manager.createPortalSession(
customer.id,
'https://your-app.com/billing'
);
// Redirect user to portal.url
Checkout Sessions#
Create checkout sessions for new signups:
typescript
const checkout = await manager.createCheckoutSession({
tier: 'pro',
billingInterval: 'monthly',
email: 'new@customer.com',
successUrl: 'https://your-app.com/success',
cancelUrl: 'https://your-app.com/cancel',
metadata: { source: 'website' },
});
// Redirect to checkout.url
Stripe Webhooks#
Handle Stripe webhooks:
typescript
// Express example
app.post(
'/webhooks/stripe',
express.raw({ type: 'application/json' }),
async (req, res) => {
const result = await manager.handleStripeWebhook(
req.body.toString(),
req.headers['stripe-signature']
);
if (result.handled) {
res.sendStatus(200);
} else {
res.sendStatus(400);
}
}
);
Billing Events#
Subscribe to billing events:
typescript
manager.onEvent(async (event) => {
switch (event.type) {
case 'subscription.created':
console.log('New subscription:', event.data);
break;
case 'invoice.paid':
console.log('Invoice paid:', event.data);
break;
case 'payment.failed':
console.log('Payment failed:', event.data);
break;
}
});
Enterprise Customers#
Set custom terms for enterprise customers:
typescript
await manager.setCustomTerms(customer.id, {
customPriceCents: 99900, // $999/month
customIncludedRequests: 500000,
customOveragePriceCents: 0.1, // $0.001/request
volumeDiscountPercent: 10,
minimumCommitmentCents: 1199800, // $11,998/year
contractStart: new Date('2024-01-01'),
contractEnd: new Date('2024-12-31'),
notes: 'Annual enterprise contract',
});
API Reference#
Pricing#
getPricingTier(tier)- Get tier configurationgetVisibleTiers()- Get all visible tiersgetMonthlyPrice(tier, interval)- Calculate monthly pricecalculateOverageCharges(tier, requests)- Calculate overageisFeatureAvailable(tier, featureId)- Check feature accessgetFeatureLimit(tier, featureId)- Get feature limitrecommendTier(monthlyRequests)- Recommend tier for usageformatPrice(cents, currency)- Format price for display
Usage Tracking#
tracker.recordRequest(params)- Record API requesttracker.getUsageSummary(customer)- Get usage summarytracker.getUsagePercentage(customer)- Get usage percentagetracker.isInOverage(customer)- Check overage statustracker.flush()- Flush batched recordstracker.stop()- Stop tracker
Invoice Management#
invoiceManager.createInvoice(customer, usage)- Create invoiceinvoiceManager.finalizeInvoice(id)- Finalize invoiceinvoiceManager.markPaid(id)- Mark as paidinvoiceManager.recordPayment(id, amount)- Record partial paymentinvoiceManager.addCredit(id, amount, description)- Add creditinvoiceManager.voidInvoice(id)- Void invoiceinvoiceManager.getOverdueInvoices()- Get overdue invoices
Subscription Management#
manager.createCustomer(params)- Create customermanager.getCustomer(id)- Get customermanager.changeTier(id, tier)- Change tiermanager.previewTierChange(id, tier)- Preview tier changemanager.cancelSubscription(id)- Cancel subscriptionmanager.reactivateSubscription(id)- Reactivatemanager.createPortalSession(id, returnUrl)- Create portalmanager.createCheckoutSession(params)- Create checkoutmanager.handleStripeWebhook(payload, signature)- Handle webhook
License#
UNLICENSED - Private package