Create Checkout Session
Initiates a Stripe Checkout session for plan selection. Returns a URL to redirect the user to Stripe.
POST /api/billing/checkout-session
Request Body
{
"plan": "pro",
"cycle": "monthly"
}
| Field | Type | Description |
|---|
plan | string | basic, pro, or enterprise |
cycle | string | monthly or annual |
Response
{
"url": "https://checkout.stripe.com/..."
}
url to complete payment.
Open Billing Portal
Returns a Stripe Customer Portal URL where the user can manage their subscription, update payment methods, and download invoices.
Response
{
"url": "https://billing.stripe.com/..."
}
Stripe Webhook
Receives Stripe webhook events. This endpoint must be configured as the webhook destination in the Stripe dashboard.
POST /api/billing/webhook
This endpoint verifies the Stripe-Signature header against your STRIPE_WEBHOOK_SECRET. Do not call this endpoint directly — it is for Stripe’s servers only.
Handled Events
| Event | Action |
|---|
checkout.session.completed | Activates the subscription |
invoice.payment_succeeded | Renews the subscription period |
invoice.payment_failed | Triggers a payment failure notification |
customer.subscription.deleted | Marks the subscription as canceled |
