Subscription will cancel on {formatDate(subscription.periodEnd)}
)}
);
}
```
## Extending Webhook Handling
Add custom webhook event handling beyond lifecycle hooks.
### Stripe: Additional Events
The `onEvent` callback in the Stripe plugin handles events not covered by Better Auth:
```typescript {% title="packages/billing/stripe/src/stripe-plugin.ts" %}
subscription: {
// ... other config
onEvent: async (event: Stripe.Event) => {
// Payment failure handling
if (event.type === 'invoice.payment_failed') {
const invoice = event.data.object;
// Extract subscription ID from the invoice
const subscriptionRef =
invoice.parent?.subscription_details?.subscription;
const subscriptionId =
typeof subscriptionRef === 'string'
? subscriptionRef
: subscriptionRef?.id;
if (subscriptionId) {
await onPaymentFailed({
subscriptionId,
customerId: typeof invoice.customer === 'string'
? invoice.customer
: invoice.customer?.id ?? '',
invoiceId: invoice.id,
amount: invoice.amount_due,
currency: invoice.currency,
attemptCount: invoice.attempt_count ?? 0,
nextPaymentAttempt: invoice.next_payment_attempt
? new Date(invoice.next_payment_attempt * 1000)
: null,
});
}
}
// Add more event handlers as needed
if (event.type === 'invoice.paid') {
// Handle successful payment
}
},
}
```
### Polar: Custom Event Handling
Polar webhooks are handled in the Polar plugin:
```typescript {% title="packages/billing/polar/src/polar-plugin.ts" %}
// See packages/billing/polar/src/hooks/ for available hooks:
// - on-subscription-created.ts
// - on-subscription-updated.ts
// - on-subscription-canceled.ts
// - on-order-paid.ts
// - on-customer-created.ts
// - on-customer-state-changed.ts
```
## Custom Billing Page Location
The default billing page is at `/settings/billing`. To customize the URLs:
```typescript {% title="packages/billing/ui/src/actions/billing-server-actions.ts" %}
const siteUrl = z.url().parse(process.env.NEXT_PUBLIC_SITE_URL);
// Customize these paths
const basePath = '/settings/billing';
const cancelReturnUrl = new URL(`${basePath}?canceled=true`, siteUrl).href;
const checkoutSuccessUrl = new URL(`${basePath}/success`, siteUrl).href;
const checkoutCancelUrl = new URL(`${basePath}/cancel`, siteUrl).href;
const portalReturnUrl = new URL(basePath, siteUrl).href;
```
## Decision Rules
**Customize seat computation when:**
- Billable seats differ from org members (exclude guests, count active only)
- You need minimum seat requirements beyond 1
- You have per-user licensing vs per-member
**Customize checkout when:**
- You need tax collection or address validation
- You want custom metadata for tracking
- You need specific trial behavior
**Customize the UI when:**
- Your pricing structure doesn't fit the default layout
- You need custom styling or branding
- You want different subscription card actions
**If unsure:** Start with defaults. Add customizations incrementally as your billing model evolves.
## Common Pitfalls
- **Seat computation returning 0**: Always ensure minimum 1 seat. Zero seats cause checkout failures.
- **Missing NEXT_PUBLIC_SITE_URL**: Server-side return URLs fail without this env var.
- **Modifying types without updating consumers**: Billing type changes can break multiple packages. Test thoroughly.
- **Forgetting Polar limitations**: Seat computation and many customizations only apply to Stripe.
- **Overriding webhook handlers**: Don't replace existing handlers; extend them. Missing handler = missed events.
- **Hardcoding URLs**: Use environment variables for URLs to separate test/prod environments.
{% faq
title="Frequently Asked Questions"
items=[
{"question": "How do I change what counts as a 'seat'?", "answer": "Modify getOrganizationMemberCount() in packages/billing/ui/src/services/billing-actions.service.ts. Filter members by your criteria."},
{"question": "Can I add a free plan?", "answer": "Yes. Add a product with hidden: true and cost: 0, or just don't require a subscription. Use defaultLimits in billing config for free tier limits."},
{"question": "Where do I customize the pricing table?", "answer": "Modify packages/billing/ui/src/components/pricing-table.tsx for layout changes, or override styles via Tailwind."},
{"question": "How do I add custom checkout fields?", "answer": "Configure custom_fields in Stripe Dashboard or pass them via getCheckoutSessionParams. Access collected data via webhooks."},
{"question": "Can I use different billing for personal vs org?", "answer": "Yes. The customerType parameter ('user' vs 'organization') controls which billing context is used."}
]
/%}
---
**Next:** [Seat Enforcement →](./seat-enforcement)