stripe

Examines your Stripe integration, identifies every gap, implements fixes, and verifies checkout flows work end-to-end. No partial modes. Every run does the full cycle.

Assumes you start on master/main. Before making code changes:

```bash

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

```

Configuration-only changes (env vars, dashboard settings) don't require a branch. Code changes do.

0. Environment Check

Detect environment mismatch first. Before any Stripe operations:

```bash

~/.claude/skills/stripe/scripts/detect-environment.sh

```

This compares your app's STRIPE_SECRET_KEY account with CLI profiles. If mismatched, resources created via CLI won't be visible to your app.

Fix mismatches:

• Use correct CLI profile: stripe -p sandbox or stripe -p production
• Or update .env.local to match your CLI account

1. Audit

Spawn the auditor. Use the stripe-auditor subagent for deep parallel analysis. It examines:

• Configuration (env vars on all deployments, cross-platform parity)
• Webhook health (endpoints registered, URL returns non-3xx, pending_webhooks = 0)
• Subscription logic (trial handling, access control, idempotency)
• Security (no hardcoded keys, secrets not logged)
• Business model compliance (single tier, trial honored on upgrade)
• Subscription management UX (settings page, billing history, portal integration)

Run automated checks:

```bash

~/.claude/skills/stripe/scripts/stripe_audit.sh

```

Research first. Before assuming current patterns are correct, check Stripe docs for current best practices. Use Gemini. What was right last year may be deprecated.

2. Plan

From audit findings, build a complete remediation plan. Don't just list issues—plan the fixes.

For each finding:

• Configuration issues → Fix directly (env vars, dashboard settings)
• Code issues → Delegate to Codex with clear specs
• Design issues → May require rethinking approach, consult stripe-design

Prioritize:

1. Critical — Blocks checkout or causes payment failures
2. High — Security issues, data integrity problems
3. Medium — Missing UX, suboptimal patterns

3. Execute

Fix everything. Don't stop at a report.

Configuration fixes (do directly):

```bash

# Missing env var

npx convex env set --prod STRIPE_WEBHOOK_SECRET "$(printf '%s' 'whsec_...')"

# Verify

npx convex env list --prod | grep STRIPE

```

Code fixes (delegate to Codex):

```bash

codex exec --full-auto "Fix [specific issue]. \

File: [path]. Problem: [what's wrong]. \

Solution: [what it should do]. \

Reference: [pattern file]. \

Verify: pnpm typecheck && pnpm test" \

--output-last-message /tmp/codex-fix.md 2>/dev/null

```

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

Webhook URL fixes:

Update in Stripe Dashboard to canonical domain. If redirects exist, use the final URL.

Missing subscription management UX:

Per stripe-subscription-ux, every integration needs:

• Settings page showing plan, status, next billing date
• Payment method display (brand + last4)
• "Manage Subscription" button (Stripe Portal)
• Billing history with downloadable invoices
• State-specific messaging (trialing, canceled, past_due)

If missing, create it. This is non-negotiable.

4. Verify

Prove it works. Not "looks right"—actually works.

Configuration verification:

```bash

npx convex env list | grep STRIPE

npx convex env list --prod | grep STRIPE

curl -s -o /dev/null -w "%{http_code}" -I -X POST "$WEBHOOK_URL"

```

Checkout flow test:

1. Create test checkout session
2. Complete with card 4242 4242 4242 4242
3. Verify webhook received (check logs)
4. Verify subscription created in Stripe Dashboard
5. Verify user state updated in database
6. Verify access granted

Webhook delivery test:

```bash

stripe events list --limit 5 | jq '.data[] | {id, type, pending_webhooks}'

# All should have pending_webhooks: 0

```

Subscription management UX test:

• Navigate to settings page
• Verify plan and status displayed
• Click "Manage Subscription" → Portal opens
• Verify billing history accessible

Business model compliance:

• Single pricing tier? ✓
• Trial honored on upgrade? (Check Stripe subscription has trial_end) ✓
• No freemium logic? (Expired trial = no access) ✓

If any verification fails, go back and fix it. Don't declare done until everything passes.

Reference business-model-preferences throughout. Key constraints:

• Single pricing tier (no complex tier logic)
• Trial completion honored on upgrade (pass trial_end to Stripe)
• No freemium (expired trial = no access, not limited access)

Assumes Next.js + TypeScript + Convex + Vercel + Clerk. Adapts gracefully to other stacks—concepts are the same, only framework specifics change.

When complete:

• Working checkout flow (test card succeeds, subscription created)
• Webhook handling with signature verification (pending_webhooks = 0)
• Subscription state management with proper trial handling
• Access control based on subscription status
• Subscription management UX (settings page, portal, billing history)
• All configuration in place (dev and prod)
• Deep verification passing

User can:

• Run test checkout with 4242 4242 4242 4242
• See subscription state update
• Access gated features
• See trial honored on mid-trial upgrade
• View and manage subscription in settings
• See payment method and billing history
• Cancel, resume, or update payment method via Portal