---
name: stripe-integration-plan
description: Plan and build a Stripe integration, such as Checkout, Billing subscriptions, Connect or webhooks, using Stripe's implementation planner and current docs, with test-mode verification. Use when the user wants to add payments, subscriptions or Stripe webhooks to their app, or asks which Stripe product to use.
---

# Plan a Stripe integration

## Steps

1. Ask, or read from the repo: what they sell (one-off, subscription, usage-based or marketplace), the stack, and where customers pay (hosted page, embedded, or mobile).
2. Run `stripe_implementation_planner` with that context to get Stripe's recommended approach, such as Checkout vs Payment Element, Billing, or Connect.
3. Check the details in current docs with `search_stripe_documentation`, and the exact API objects with `stripe_api_search` and `stripe_api_details`. Prefer the newest recommended APIs over older ones you remember.
4. Write the plan:
   - products and prices to create;
   - server endpoints, such as creating a Checkout Session, and the client changes;
   - webhooks to handle (at least `checkout.session.completed` and `invoice.paid` or `invoice.payment_failed` for subscriptions), with signature verification;
   - test cards and test clocks for subscriptions.
5. When the repo is open, implement it step by step, with keys read from environment variables.
6. Create test-mode products or prices with `stripe_api_write` only after the user approves, and never in live mode during setup.

## Done means

A full test-mode payment works end to end, the webhook handler verifies signatures, and the user has a short checklist for going live.