Billing & Stripe API

Internal documentation for developers. This page covers Stripe integration patterns, webhook handling, checkout flows, and plan-gating logic. Not intended for end users.

Route Map

Method	Endpoint	Handler File	Description
`POST`	`/api/stripe/create-checkout-session`	`stripe/create-checkout-session/route.ts`	Create a Stripe Checkout session
`POST`	`/api/stripe/customer-portal`	`stripe/customer-portal/route.ts`	Create a Stripe Customer Portal session
`GET`	`/api/stripe/get-checkout-session`	`stripe/get-checkout-session/route.ts`	Retrieve a checkout session result
`GET`	`/api/stripe/prices`	`stripe/prices/route.ts`	List available plan prices
`POST`	`/api/stripe/proration-preview`	`stripe/proration-preview/route.ts`	Preview subscription proration before upgrade
`POST`	`/api/stripe/usage-credits`	`stripe/usage-credits/route.ts`	Add/manage usage credits
`POST`	`/api/stripe/validate-downgrade`	`stripe/validate-downgrade/route.ts`	Validate if downgrade is safe
`POST`	`/api/stripe/referral`	`stripe/referral/route.ts`	Apply referral discount
`POST`	`/api/stripe/webhook`	`stripe/webhook/route.ts`	Receive Stripe webhook events

Stripe Client Setup

The Stripe client is initialized in @zappway/lib/stripe (or similar). The API key is loaded from STRIPE_SECRET_KEY environment variable.

import { stripe } from '@zappway/lib/stripe';

Checkout Flow

1. User selects a plan in the UI
   POST /api/stripe/create-checkout-session { priceId, successUrl, cancelUrl }
   → Creates Stripe Checkout Session
   → Returns { url } for redirect

2. User completes payment on Stripe-hosted page
   → Stripe redirects to successUrl with ?session_id=...

3. App fetches session result
   GET /api/stripe/get-checkout-session?session_id=...
   → Validates payment success
   → Returns subscription status

4. Stripe fires webhook
   POST /api/stripe/webhook
   → Updates organization subscription in DB

Webhook Handler

The webhook is the source of truth for subscription state. All plan changes must go through the webhook, not the checkout session response.

// Webhook signature verification (mandatory)
const event = stripe.webhooks.constructEvent(
  body,
  req.headers.get('stripe-signature'),
  process.env.STRIPE_WEBHOOK_SECRET
);

Key events handled:

Stripe Event	Action
`checkout.session.completed`	Activate subscription
`customer.subscription.updated`	Update plan features
`customer.subscription.deleted`	Downgrade to free tier
`invoice.payment_failed`	Flag payment failure, notify user
`invoice.paid`	Reset usage counters for new period

Plan Gating

Plans gate access to features via the session’s subscription metadata. The pattern used across the app:

// Example: Personal Assistant plan gate
import { assertPersonalAssistantPlan } from '@zappway/lib/personal-assistant';
assertPersonalAssistantPlan(req.session); // throws 403 if plan doesn't include feature

Similar assertXxxPlan helpers exist for other premium features. They read from req.session.organization.subscription (loaded from DB via NextAuth callbacks).

Proration Preview

Before upgrading, the UI calls proration preview to show the user the exact charge:

// POST /api/stripe/proration-preview
// Body: { newPriceId: string }
// Returns: Stripe InvoicePreviewParams result

Usage Credits

The usage-credits endpoint manages prepaid credits for usage-based billing (e.g., message volume). Credits are stored in the DB and decremented on each billable event.

Validate Downgrade

Checks if the org’s current resource usage is compatible with a lower plan:

// POST /api/stripe/validate-downgrade
// Body: { targetPriceId: string }
// Returns: { canDowngrade: boolean, blockers: string[] }
// blockers example: ['You have 15 active agents, plan limit is 5']

Environment Variables Required

Variable	Description
`STRIPE_SECRET_KEY`	Stripe secret key (server-side only)
`STRIPE_WEBHOOK_SECRET`	Webhook endpoint secret for signature verification
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	Stripe publishable key (client-side)

Known Issues / Gotchas

Webhook idempotency: Stripe can deliver the same event multiple times. All webhook handlers must be idempotent — use stripe_event_id as a dedup key stored in the DB.
Checkout session expiration: Sessions expire after 24 hours. If the user abandons checkout and returns later, they need a new session.
validate-downgrade must check ALL resource types that have plan limits (agents, skills, datastores, team members, etc.). If a new resource type gets a plan limit, this endpoint must be updated.
Customer Portal URL expires after 5 minutes — generate it on-demand, never cache it.

API Internals

Infrastructure

Route Map

Stripe Client Setup

Checkout Flow

Webhook Handler

Plan Gating

Proration Preview

Usage Credits

Validate Downgrade

Environment Variables Required

Known Issues / Gotchas

​Route Map

​Stripe Client Setup

​Checkout Flow

​Webhook Handler

​Plan Gating

​Proration Preview

​Usage Credits

​Validate Downgrade

​Environment Variables Required

​Known Issues / Gotchas

Route Map

Stripe Client Setup

Checkout Flow

Webhook Handler

Plan Gating

Proration Preview

Usage Credits

Validate Downgrade

Environment Variables Required

Known Issues / Gotchas