Laptop with pricing spreadsheet for vibe coding tool costs

20 Copy-Paste Prompts for Stripe Billing, Webhooks, and Customer Portal

Stripe billing prompts save vibe coders from retyping the same webhook, Checkout, and Customer Portal instructions every sprint — if the prompts enforce idempotency, raw body verification, and server-only secrets. Copy-paste is not cheating; unstructured paste is how duplicate subscriptions get created. Below are 20 numbered prompts for Cursor, Claude Code, Lovable exports, and Aider — each scoped for one merge-sized task. Updated November 2026.

Developer copying structured AI prompts for Stripe billing integration into a coding agent session
Good billing prompts read like tickets — outcome, constraints, files, and definition of done.

Deploy and env var hygiene come first: deploy a vibe-coded app to Vercel with separate Preview and Production Stripe keys. For auth linkage to customer records, read add auth to a vibe-coded Next.js app.

Table of contents

  1. How to use these prompts
  2. Checkout and session prompts (1–5)
  3. Webhook prompts (6–12)
  4. Customer Portal prompts (13–16)
  5. Ops, testing, and hardening (17–20)
  6. Anti-patterns to add to every prompt
  7. FAQ

How to use these prompts

Replace bracketed placeholders with your paths and IDs. Run one prompt per branch when possible. Append this block to any prompt:

Do not expose secret keys in client components. Verify webhook signatures with raw body. Make webhook handlers idempotent. Do not grant entitlements only on success redirect pages.

Stack assumed: Next.js App Router, TypeScript, Supabase or Postgres ORM, Stripe SDK latest. Adapt API route paths if your repo differs.

Checkout and session prompts (1–5)

1. Create POST /api/stripe/checkout that accepts authenticated userId, creates or reuses Stripe Customer by email, starts Checkout Session mode=subscription with STRIPE_PRICE_ID_PRO from env, success_url and cancel_url on my domain, metadata { supabaseUserId }. Return session.url JSON. Server-only STRIPE_SECRET_KEY.

2. Add GET /api/stripe/checkout/status?session_id= that retrieves Checkout Session server-side and returns payment_status and subscription id without exposing secrets. Require auth; users may only query their own sessions via metadata match.

3. Implement pricing page button that calls /api/stripe/checkout and redirects to session.url. Disable double-submit while loading. Show toast on error from API JSON message.

4. Add 7-day trial to Checkout Session using subscription_data.trial_period_days: 7 for price STRIPE_PRICE_ID_PRO. Document in code comment that webhook checkout.session.completed still required for entitlements.

5. Support multiple plans: env STRIPE_PRICE_ID_BASIC and STRIPE_PRICE_ID_PRO; pass priceId in POST body; validate against allowlist server-side; reject unknown price IDs with 400.

Webhook prompts (6–12)

6. Create POST /api/stripe/webhook using request.text() raw body and stripe.webhooks.constructEvent with STRIPE_WEBHOOK_SECRET. Export runtime nodejs and disable body parser if needed for this route only.

7. Handle checkout.session.completed: read metadata supabaseUserId, store stripeCustomerId and subscriptionId in subscriptions table with status active and current_period_end from subscription object.

8. Add stripe_events table with event_id primary key. Before processing any webhook, insert event_id; on conflict skip processing and return 200. Log skipped duplicates.

9. Handle customer.subscription.updated and customer.subscription.deleted: sync status and current_period_end to subscriptions table by stripe subscription id. Revoke premium when status canceled or unpaid past grace.

10. Handle invoice.payment_failed: mark subscription past_due in DB and send optional hook placeholder for email job. Do not delete user account.

11. Write integration test or script using Stripe fixture event checkout.session.completed with mocked signature helper for local CI. Document stripe listen --forward-to for dev.

12. Add admin-only debug route or script to reconcile Stripe subscriptions list for one customer against DB rows and print mismatches — never expose in production without auth.
Stripe webhook event flow connecting payment events to database subscription records
Prompts 6–12 are one chain — run webhook verification before entitlement logic.

Customer Portal prompts (13–16)

13. Create POST /api/stripe/portal that accepts authenticated user, loads stripeCustomerId from DB, creates billingPortal.sessions.create with return_url to /settings/billing, returns url for redirect.

14. Add Settings / Billing page with Manage subscription button calling portal route. Show current plan name and renewal date from DB not from client guess.

15. Configure Stripe Customer Portal in dashboard comments checklist: allow cancel, payment method update, invoice history. Align cancel behavior with webhook subscription.deleted handler.

16. Gate premium routes in middleware using DB subscription status active or trialing only. Do not read Stripe from client. Return 402 JSON for API routes when inactive.

Ops, testing, and hardening (17–20)

17. Add .env.example entries for STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_ID_PRO, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY with comments server-only vs public. Fail build-time script if secret key starts with NEXT_PUBLIC.

18. Write TESTING-STRIPE.md with steps: test card 4242..., CLI listen, trigger events, expected DB states table for checkout success, cancel, failed payment.

19. Add structured logging on webhook handler: event type, event id, user id metadata — never log full card or secret keys. Return 200 within 3 seconds; defer heavy work if needed.

20. Security pass on all Stripe routes: auth required on checkout and portal, webhook signature mandatory, rate limit checkout POST per user, align with security checklist for AI-generated apps — list findings in comment block.

Anatomy of a billing prompt that agents obey

Every prompt in the list below follows a hidden template: Outcome → Constraints → Files → Verify. Weak prompts skip constraints; agents then expose secrets or skip webhooks. Strong opening line example: “Add idempotent Stripe webhook at app/api/stripe/webhook/route.ts using raw body — do not modify checkout route in this turn.”

When adapting prompts to Lovable exports, prepend: “Map API routes to pages/api if Pages Router detected.” When adapting to server actions stack, specify “use server action for checkout creation instead of route handler” — agents otherwise default to App Router API routes from training bias.

Recommended prompt chains by sprint

Sprint 1 — Money in: prompts 1, 6, 7, 8. Definition of done: test checkout completes; webhook writes subscription row; duplicate event ignored.

Sprint 2 — Self-serve: prompts 13, 14, 15, 16. Definition of done: user opens Portal, cancels, webhook revokes access within one minute.

Sprint 3 — Hardening: prompts 17, 18, 19, 20 plus manual live card test. Definition of done: security pass documented; TESTING-STRIPE.md reproducible by future you.

Do not start Sprint 2 until Sprint 1 event logs are green in Stripe Dashboard. Customer Portal cancel events expose missing subscription.deleted handlers — fix in Sprint 1 chain first.

Environment scoping prompts (bonus pattern)

Bonus A. Audit all process.env usages for STRIPE_* keys. List any NEXT_PUBLIC_ prefix on secret keys as ERROR. Output table: variable name, file, line, fix suggestion.

Bonus B. Add Vercel deployment comment block in README: which Stripe webhook secret maps to Preview vs Production URLs, and how to run stripe listen locally against npm run dev port.

These bonus patterns pair with prompt 17 — env mistakes cause more production billing outages than Stripe API version drift among vibe-coded SaaS apps.

What agents get wrong on prompts 6–12

  • Using req.json() before constructEvent — signature verification always fails
  • Putting webhook handler in Edge runtime without raw body support — read runtime docs before accept
  • Creating subscriptions table without unique constraint on user_id — duplicate rows on webhook retry
  • Logging full event payload in production — PCI and privacy noise
  • Returning 500 on duplicate idempotent skip — Stripe retries aggressively; return 200 when safely ignored

Review checklist after any webhook prompt: read handler top to bottom, grep for json() on webhook route, run CLI trigger twice, confirm one DB row.

Anti-patterns to add to every prompt

  • Do not use Charges API or legacy Sources for new subscriptions
  • Do not hardcode test price IDs in production branches
  • Do not parse webhook JSON before signature verification
  • Do not unlock features in success page useEffect without DB check
  • Do not store PCI-sensitive data in your database

Chain prompts 6 → 7 → 8 before testing checkout end-to-end. Portal prompts 13–16 assume webhook sync already works. See also system prompt templates for reusable guardrails and the starter stack for env scoping on Vercel.

Prompt rangeRun afterVerify with
1–5Auth worksTest Checkout redirect
6–12DB schema existsStripe CLI events
13–16Webhooks sync statusPortal cancel test
17–20Feature completeChecklist + live card

Adapting prompts for Lovable and Bolt exports

Builder exports often ship client-side Stripe calls or fake billing UI without webhooks. Before prompts 1–20, run architecture prompt zero: “Audit repo for Stripe usage; list client-side secret key violations; migrate checkout and webhook to server routes; output file move plan.” Then run numbered prompts against corrected structure.

Exports may use Supabase edge functions instead of Next API routes — replace path strings in prompts but keep idempotency and raw body requirements identical. Payment logic is host-agnostic; security rules are not.

Human review gates for billing prompts

After each prompt merge, human review gates non-negotiable for billing:

  1. Read full diff — no skipped files because “agent said done”
  2. Grep STRIPE_SECRET and sk_live in repo — zero client exposure
  3. Run Stripe CLI event twice — confirm idempotent skip in logs
  4. Check Dashboard webhook delivery for 200 responses

Twenty prompts without review gates produces billing-shaped malware — UI that charges without entitlements or entitlements without payment. Treat prompts as accelerators for careful engineers, not replacements.

Stripe Dashboard settings to verify after prompts

Prompts write code; Dashboard settings kill production silently. After prompt chain completes, manually verify:

  • Customer Portal activation and allowed actions match prompt 15 assumptions
  • Webhook endpoint shows recent 200s with correct event types subscribed
  • Products and prices in live mode match env var IDs — not test mode IDs copied by mistake
  • Business settings → Customer emails enabled if you rely on Stripe receipts
  • Radar rules reviewed if you sell globally — AI does not configure fraud tools

Keep a screenshot folder of correct Dashboard settings dated per deploy — debugging “webhook worked yesterday” without baseline wastes hours agents cannot recover. Share TESTING-STRIPE.md with any cofounder or contractor before they touch billing code — payment regressions are team sport failures even on solo-founder repos.

FAQ

Can I paste all 20 prompts at once?

You can, but you will get unmaintainable diffs and missed edge cases. Treat each numbered prompt as one ticket. Merge green before the next.

Do these work for Lovable or Bolt exports?

Yes with path edits. Exports often use different API folder layouts — first prompt should map your actual route directory before billing logic.

Supabase vs Prisma in prompts?

Replace “subscriptions table” with your ORM calls. Schema-first prompt: add columns stripe_customer_id, stripe_subscription_id, status, current_period_end with unique constraints on user_id.

What if webhook always returns 400?

Run prompt 6 alone. Almost always raw body or wrong webhook secret for that environment. Preview deployments need their own endpoint and secret in Stripe Dashboard.

Where do I store these prompts in my repo?

Create docs/stripe-prompts.md with numbered prompts and checkboxes per sprint. Version control prompts like code — when Stripe SDK changes, update prompt constraints in same PR as dependency bump. Agents read repo docs when @mentioned; keep prompts discoverable.

Do I need Stripe Tax or invoicing prompts too?

Not in the base 20 — add separate prompts after core billing works. Tax automation depends on jurisdiction nexus; AI guesses wrong on VAT. Ship checkout and portal first; tax is sprint four with accountant input, not prompt 21 autopilot.

Soft CTA: Copy prompt 6 into a fresh branch tonight and get webhook verification green with Stripe CLI before you run prompt 7. Twenty prompts is a billing backlog — treat it like a sprint board, not one mega-chat. When Checkout and Portal work, run the security checklist before your first real charge.

Leave a Reply

Your email address will not be published. Required fields are marked *