Stripe Design
Create a design document for Stripe integration.
Objective
Produce a clear, implementable design that follows our business model preferences and current Stripe best practices.
Process
1. Understand Requirements
What does this app need? Usually one of:
- Subscription billing (most common)
- One-time payments
- Both
Reference business-model-preferences for constraints: single tier, trial with completion on upgrade, no freemium.
2. Research Current Patterns
Stripe's API evolves. Before designing:
- Use Gemini to check current Stripe Checkout best practices
- Verify webhook event recommendations
- Check if there are new patterns for your use case
Don't assume last year's patterns are still optimal.
3. Design the Integration
Produce a design document covering:
Checkout Flow
- Embedded or redirect?
- What mode? (subscription, payment, setup)
- Customer creation strategy
- Success/cancel URLs
- Trial strategy: Credit card upfront (preferred) with
trial_period_days
Webhook Events
- Which events to handle?
- Idempotency strategy
- Error handling approach
Subscription State
- What fields to store locally?
- Access control logic
- Trial handling
Price Structure
- Monthly price (and annual if applicable)
- Trial duration
4. Get Validation
Run the design through Thinktank for multi-perspective review. Billing is critical — get expert opinions before implementation.
Output
A design document that stripe-scaffold can implement. Include:
- Architecture decisions with rationale
- Specific Stripe API features to use
- Data model for subscription state
- Webhook events to subscribe to
- Access control logic
Adaptation
Design for the detected stack (usually Next.js + Convex + Clerk). If stack differs, adapt the design to that stack's patterns while maintaining the same Stripe concepts.