Stripe Scaffold

Generate the code for a Stripe integration.

Branching

Assumes you start on master /main . Before generating code:

git checkout -b feat/stripe-integration-$(date +%Y%m%d)

Objective

Turn a design document into working code. Delegate implementation to Codex aggressively — that's what it's for.

Process

1. Review the Design

Read the design document from stripe-design . Understand:

• Checkout flow

• Webhook events

• State management approach

• Access control logic

2. Research Current Implementation

Before generating code:

• Use Gemini to find current Stripe SDK usage patterns

• Check the Stripe docs for your specific use case

• Look at how similar apps implement this

Code patterns change. Don't rely on cached knowledge.

3. Delegate to Codex

For each component, delegate to Codex with clear specs:

codex exec --full-auto "Implement Stripe webhook handler for [events].
Follow pattern in [reference]. Use Convex mutations for state updates.
Verify signature first. Handle idempotency.
Run pnpm typecheck after."
--output-last-message /tmp/codex-webhook.md 2>/dev/null

Then: git diff --stat && pnpm typecheck && pnpm test

4. Components to Generate

Typical Next.js + Convex stack:

Backend:

• src/lib/stripe.ts — Stripe client initialization

• src/app/api/stripe/checkout/route.ts — Checkout session creation

• src/app/api/stripe/webhook/route.ts — Webhook receiver (signature verification)

• convex/stripe.ts — Webhook event processing

• convex/subscriptions.ts — Subscription state management

• convex/billing.ts — Billing queries and portal session creation

• convex/schema.ts updates — Subscription fields on users

• .env.example updates — Document required variables

Subscription Management UX (Required): Reference stripe-subscription-ux for full requirements.

• components/billing/SubscriptionCard.tsx — Current plan overview

• components/billing/BillingCycleInfo.tsx — Next billing date, amount

• components/billing/PaymentMethodDisplay.tsx — Card on file

• components/billing/BillingHistory.tsx — Past invoices

• components/billing/ManageSubscriptionButton.tsx — Opens Stripe Portal

• components/billing/TrialBanner.tsx — Trial status/countdown

• Settings page section for subscription management

This UX is non-negotiable. No Stripe integration is complete without it.

5. Don't Forget

• Trial handling: pass trial_end when user upgrades mid-trial

• Access control: check subscription status before gated features

• Error handling: webhook should return 200 even on processing errors (to prevent Stripe retries)

• Signature verification: MUST be first thing in webhook handler

Quality Gates

After generation:

• pnpm typecheck — No type errors

• pnpm lint — No lint errors

• pnpm test — Tests pass (if they exist)

• Manual review of generated code

Adaptation

Default stack is Next.js + Convex. If different:

• Express/Fastify: Different route setup, same Stripe logic

• Supabase/Postgres: Different ORM, same state management concepts

• No Convex: Webhook processing happens in the API route directly

The Stripe parts are the same; the framework parts adapt.