playbooks

home / skills / phrazzld / claude-config / stripe-design

stripe-design skill

/skills/stripe-design

This skill creates a Stripe integration design document with architecture decisions, API features, and data models aligned to business preferences and best

npx playbooks add skill phrazzld/claude-config --skill stripe-design

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.0 KB
---
name: stripe-design
description: |
  Design a Stripe integration based on business requirements and organizational preferences.
  Produces a design document that stripe-scaffold will implement.
---

# 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

**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.

Overview

This skill designs a production-ready Stripe integration based on business requirements and organizational preferences. It produces a clear, implementable design document that stripe-scaffold can use to generate code and configuration. The design prioritizes current Stripe best practices, idempotent webhooks, and a minimal local subscription state model.

How this skill works

It inspects the business-model-preferences and detected tech stack to choose a checkout pattern (redirect vs embedded), price model, and webhook subscription list. It recommends specific Stripe API features (Checkout, Customer objects, Subscriptions, Price objects, SetupIntents) and defines a local data model for subscription state and access control. Finally, it outputs architecture decisions, API calls, webhook handlers, and error/idempotency strategies for review.

When to use it

  • You need a single-tier subscription with optional trial and no freemium.
  • You want a reliable subscription or one-time payment flow using Stripe Checkout or Payment Links.
  • You need a documented webhook strategy and local subscription state model for access control.
  • You must integrate Stripe into an existing stack (e.g., Next.js + Convex + Clerk) with clear implementation guidance.
  • You want a reviewable design before generating code with stripe-scaffold.

Best practices

  • Prefer Stripe Checkout redirect for simple, secure flows; use Payment Links or embedded Elements only when customization demands it.
  • Create a dedicated Stripe Customer for each authenticated user and attach payment methods via SetupIntent for future billing.
  • Store minimal subscription state locally: subscription id, status, current_period_end, price_id, trial_end, and latest_invoice_id; derive access from status and current_period_end.
  • Implement idempotency and retry logic for webhook processing, record processed webhook IDs, and respond with 2xx only after successful processing.
  • Validate design with a multi-role review (billing engineer, security, product) before implementation.

Example use cases

  • Single-tier monthly subscription with a 14-day trial that converts on upgrade or payment method attachment.
  • One-time payment checkout for digital goods with optional customer creation for future purchases.
  • Hybrid app offering one-time setup fees plus recurring monthly subscription billed via the same Customer object.
  • Migrating a legacy billing system to Stripe while keeping a minimal local access-control model.
  • Using Next.js + Clerk: create customer on first auth, redirect to Checkout, handle webhooks in serverless API route, persist subscription state in Convex.

FAQ

Should I create Stripe Customers before Checkout or on checkout.session.completed?

Create a Customer ahead only if you need to attach payment methods or track billing before purchase. Otherwise create on checkout.session.completed and link the returned customer id to your user record.

Which webhook events are mandatory?

Handle checkout.session.completed, invoice.payment_succeeded, invoice.payment_failed, and customer.subscription.updated/created/canceled. These cover subscription lifecycle and payment outcomes; add more only as needed.