stripe-saas-ops

name	stripe-saas-ops
description	Plan, implement, verify, and operate Stripe SaaS billing. Use when Codex needs to handle Stripe Checkout, subscriptions, products, prices, customer portal, webhooks, entitlements, test-mode verification, Stripe CLI workflows, billing docs, secret management, or human Stripe Dashboard setup tasks for a web app.

Stripe SaaS Ops

Freshness

These instructions are based on official Stripe documentation reviewed on 2026-06-24. The subscription guide examples referenced Stripe API versions including 2026-05-27.dahlia and preview examples including 2026-04-22.preview; treat those as documentation context, not a repo-wide API version decision. Re-check official Stripe docs before changing production billing, taxes, webhook events, API versions, or Dashboard configuration.

Goal

Make SaaS billing simple, testable, and hard to misuse: product/pricing decisions are explicit, all secret-bearing work stays server-side, Checkout is preferred for V1, subscription state is driven by webhooks, customer self-service uses the billing portal, and human Dashboard tasks are separated from code work.

Default Approach

Assume a small React/Vite/Firebase app unless the repo shows otherwise.

• Use Stripe Checkout for V1 subscription purchase.
• Use Stripe-hosted customer portal for subscription management.
• Keep product and price IDs server-trusted; never let the client decide authoritative amounts.
• Use webhooks for subscription, invoice, payment, and entitlement state.
• Store app entitlements in the app database only after webhook verification.
• Use Stripe test mode, Stripe CLI, test cards, and webhook forwarding for local verification.
• Keep Stripe secret keys and webhook signing secrets out of client bundles and committed files.

Workflow

1. Inspect the repo. Identify framework, backend boundary, existing payment code, env handling, database, tests, and docs.

2. Classify the task. Read references/task-routing.md to choose setup, pricing, checkout, webhooks, portal, entitlements, testing, or operations.

3. Separate human Dashboard tasks from code tasks. Human tasks include creating Stripe account resources, selecting tax behavior, creating products/prices, configuring customer portal, creating webhook endpoints, copying secrets, and approving live-mode launch.

4. Design the billing model first. Keep V1 pricing simple. Prefer one paid plan or one free trial plus one paid plan unless the product truly needs tiers.

5. Put trusted billing logic on the server. For Firebase apps, use Cloud Functions for Checkout Session creation, portal session creation, webhook handling, and entitlement mutation.

6. Verify with Stripe test mode. Test successful payment, failed payment, cancellation, renewal/invoice events where applicable, and webhook replay/idempotency behavior.

7. Document operations. Update docs/stripe.md and docs/env.md with Dashboard setup, env vars, local testing, webhook events, deployment, and rollback notes.

Reference Files

• Read references/task-routing.md to choose the Stripe workflow.
• Read references/setup-and-pricing.md before planning products, prices, trials, tax, or Dashboard setup.
• Read references/checkout-portal-entitlements.md before implementing Checkout, customer portal, or app access.
• Read references/webhooks-and-testing.md before implementing or changing webhook handling or verification.

Operating Rules

• Never commit Stripe secret keys, restricted keys, webhook signing secrets, or live-mode credentials.
• Never expose secret keys in Vite VITE_* env vars or any browser bundle.
• Never trust price IDs, customer IDs, or entitlement claims from the client without server validation.
• Fulfill access from verified webhook events, not from the Checkout redirect alone.
• Make webhook handling idempotent; Stripe can deliver events more than once.
• Keep live mode and test mode clearly separated in docs, env vars, and Dashboard tasks.
• Do not deploy or mutate live Stripe resources unless the user explicitly asks and credentials are available.

Outputs

For planning tasks, produce:

• Billing model summary.
• Stripe Dashboard human setup checklist.
• Required env vars and secrets.
• Checkout and portal flow.
• Webhook events and entitlement mapping.
• Test plan and launch checklist.

For implementation tasks, produce:

• Server-side Stripe integration changes.
• Client UI changes limited to pricing, redirect, status, and portal entry.
• Webhook/idempotency changes.
• Updated docs.
• Verification results.