;
}
if (session.status === "open") {
// Payment still pending
return
Payment in progress...
;
}
return
Payment failed
;
}
```
## Webhook Integration
This endpoint only starts the checkout flow—**subscription activation and billing history are synced by `/api/webhooks/stripe`**.
The webhook handler listens to these events:
| Event | Purpose |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| `customer.subscription.created` | Upserts the initial record in `user_subscriptions` using metadata from the Checkout session |
| `customer.subscription.updated` | Handles plan changes, cancellations, renewals, and billing-cycle changes |
| `customer.subscription.deleted` | Marks subscriptions as canceled in the database |
| `invoice.payment_succeeded` | Inserts a payment record into `payment_history` |
| `invoice.payment_failed` | Logs failed payments so you can notify the customer |
Because the handler reads the `user_id` from metadata you set in `checkout_sessions`, **webhooks must run even if the user never returns to `/success`**.
See [Stripe Webhook Handler](/api-reference/endpoint/stripe-webhooks) for the full implementation details.
Never rely solely on the success page to activate subscriptions. Users can close the browser before returning. Always use webhooks for reliable subscription management.
## Testing
### Test with Stripe Test Cards
Use Stripe's test cards to simulate payments:
```bash theme={null}
# Successful payment
Card: 4242 4242 4242 4242
Expiry: Any future date
CVC: Any 3 digits
ZIP: Any 5 digits
```
### Test Workflow
```bash theme={null}
stripe listen --forward-to localhost:3000/api/webhooks/stripe
```
This forwards webhook events to your local server.
```bash theme={null}
pnpm dev
```
1. Sign in to your app
2. Go to `/pricing`
3. Click "Subscribe" on any plan
4. You'll be redirected to Stripe Checkout (test mode)
1. Fill form with test card `4242 4242 4242 4242`
2. Click "Subscribe"
3. Stripe processes payment and redirects to `/success`
Check your terminal running Stripe CLI. You should see one of the subscription or invoice events:
```
✔ Received event: customer.subscription.created
✔ Forwarded to http://localhost:3000/api/webhooks/stripe
✔ Response: 200
```
For invoice flows, you can also trigger:
```bash theme={null}
stripe trigger invoice.payment_succeeded
```
Verify `user_subscriptions` and `payment_history` tables updated:
```sql theme={null}
SELECT * FROM user_subscriptions WHERE user_id = 'your-user-id';
SELECT * FROM payment_history WHERE user_id = 'your-user-id';
```
## Troubleshooting
**Cause:** User not authenticated or session expired.
**Fix:**
1. Verify user is signed in
2. Check Supabase session cookie exists
3. Test with `supabase.auth.getUser()` in browser console
**Cause:** Missing or invalid `price_id` parameter.
**Fix:**
1. Verify form includes `price_id` field
2. Check Price ID format: `price_...` (not `prod_...`)
3. Ensure Price ID exists in Stripe Dashboard
4. Test with hardcoded Price ID first
**Cause:** Stripe API error, network issue, or invalid configuration.
**Fix:**
1. Check `STRIPE_SECRET_KEY` environment variable
2. Verify Stripe key matches mode (test vs live)
3. Check browser console for errors
4. Inspect server logs for Stripe API errors
**Cause:** Webhook not received or webhook handler error.
**Fix:**
1. Verify Stripe CLI running: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`
2. Check webhook endpoint: `POST /api/webhooks/stripe`
3. Verify `STRIPE_WEBHOOK_SECRET` environment variable
4. Check webhook handler logs for errors
5. Test webhook: `stripe trigger checkout.session.completed`
**Cause:** Request made without origin header (e.g., from Postman).
**Fix:**
Use browser fetch or add origin header manually:
```bash theme={null}
curl -X POST 'http://localhost:3000/api/checkout_sessions' \
-H 'Origin: http://localhost:3000' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'price_id=price_...'
```
## Security Considerations
The endpoint checks for an active Supabase session. Unauthenticated requests return `401`.
**Why:** Prevents anonymous users from creating checkout sessions and ensures proper user-subscription linking.
User ID and email are stored in Stripe metadata:
```ts theme={null}
metadata: {
user_id: user.id,
user_email: user.email || "",
}
```
**Purpose:** Webhooks use this to update the correct `user_subscriptions` record.
**Privacy:** Email stored in Stripe only, not exposed publicly.
The success page should verify the session ID with Stripe:
```ts theme={null}
const session = await stripe.checkout.sessions.retrieve(sessionId);
```
**Why:** Prevents users from forging success URLs to fake payments.
The endpoint doesn't return the Checkout session object (contains sensitive data). It only redirects to Stripe.
**Best practice:** Stripe handles all payment details securely on their PCI-compliant infrastructure.
## Related Documentation
Complete Stripe integration guide including webhooks, plans, and testing.
Allow users to manage their subscriptions, update payment methods, and view invoices.
Handle subscription lifecycle events and keep your database in sync.
Set up Stripe API keys and webhook secrets for local and production environments.