A ready-to-use Stripe integration project template with predefined phases, tasks, milestones, and effort estimates to plan, integrate payments, subscriptions, webhooks, and launch secure checkout with best practices.
Sign up for Kriyastream to start using this template and many others for your projects.
| Phase/Task | Estimate | Assign To |
|---|---|---|
Configuration & Operations2d Stripe Dashboard setup, env vars, webhook config, and PlanTierProduct sync. | ||
Stripe Dashboard – Products & Prices1d Document and/or automate: create Products and Prices in Stripe with correct lookup_key values that match PlanTierProduct.pricingLookupKey. Ensure at least Free, Pro, Team (or equivalent) exist. | ||
Define and document lookup_key values for each plan tier | 2h | Software Development - Full-stack Developer |
Create or verify Products and Prices in Stripe Dashboard (or script) | 3h | Software Development - Full-stack Developer |
Environment variables Document required env: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET. Add to .env.template or setup doc. | ||
Update env template or setup documentation with Stripe variables | 1h | Software Development - Full-stack Developer |
Webhook endpoint configuration1d Document webhook URL (e.g. https://<host>/api/stripe/webhook) and events to subscribe. Include Stripe CLI command for local testing. | ||
List events: checkout.session.completed, customer.subscription.*, invoice.*; add Stripe CLI listen command to docs | 2h | Software Development - Full-stack Developer |
PlanTierProduct seed/sync Ensure each plan tier has a corresponding PlanTierProduct with correct externalPriceId, pricingLookupKey, and optionally externalProductId for Stripe. | ||
Verify or add seed script / sync from Stripe | 2h | Software Development - Full-stack Developer |
Checkout & Customer Model5d Stripe Customer strategy, portal by customer ID, submit auth and idempotency. | ||
Create/link Stripe Customer (if strategy is B)2d Before checkout: fetch or create Stripe Customer for org; pass customerId into createCheckoutSession; persist externalCustomerId on subscription create/update. | ||
Implement create/fetch Stripe Customer in checkout flow | 3h | Software Development - Full-stack Developer |
Persist externalCustomerId in submit or webhook | 2h | Software Development - Full-stack Developer |
Stripe Customer strategy Decide: (A) continue guest-style (new customer per checkout), or (B) create/link Stripe Customer per org and pass customerId into createCheckoutSession. If (B), add storage for externalCustomerId. | ||
Document decision and if B schema/API for externalCustomerId | 1h | Software Development - Full-stack Developer |
Billing portal by customer ID1d If strategy B: add Manage billing path that opens portal using stored customerId (no checkout session_id required). | ||
Add UI entry and API path for portal by customerId1d | 2h | Software Development - Full-stack Developer |
Submit endpoint – auth and idempotency1d (1) Only authenticated users (and org membership) can call POST /api/subscription/submit. (2) Make submit idempotent keyed by session_id. | ||
Add auth and org check to submit route | 2h | Software Development - Full-stack Developer |
Implement idempotent upsert for subscription and invoice by session_id | 3h | Software Development - Full-stack Developer |
Webhook Hardening & Sync2d Handle checkout.session.completed and subscription.updated; idempotency; cleanup legacy config. | ||
Handle checkout.session.completed in webhook1d In webhook on checkout.session.completed: create or update internal subscription and invoice (mirror submit logic) for eventual consistency. Idempotent by session.id. | ||
Implement handler with same logic as submit (plan lookup subscription upsert invoice) | 5h | Software Development - Full-stack Developer |
Ensure idempotent by session id or subscription id | 2h | Software Development - Full-stack Developer |
Handle customer.subscription.updated On customer.subscription.updated sync plan/price to internal subscription (map Stripe price to PlanTierProduct; update planTierId / externalSubscriptionId). | ||
Implement subscription.updated handler and map price to PlanTierProduct | 3h | Software Development - Full-stack Developer |
Idempotency for subscription/invoice in webhook1d Ensure all webhook handlers that create/update subscriptions and invoices are idempotent (e.g. by Stripe subscription id or invoice id). | ||
Review and add idempotency guards where needed | 2h | Software Development - Full-stack Developer |
Remove or update legacy route config In webhook route remove or document config.api.bodyParser = false (App Router uses req.text() for raw body). | ||
Remove ineffective config or add comment for future readers | 1h | Software Development - Full-stack Developer |
API & Route Fixes Next.js 15 create-portal-session params; standardized errors and logging. | ||
Create-portal-session – params in App Router In create-portal-session route use Next.js 15 convention: accept params as Promise and await before use so orgId is correct in returnUrl. | ||
Change route to await params and use resolved orgId | 1h | Software Development - Full-stack Developer |
Error responses and logging Standardize error responses (JSON { error: string }) and logging for create-checkout-session create-portal-session submit and webhook. Avoid leaking Stripe or internal details. | ||
Audit and update error responses and log messages | 2h | Software Development - Full-stack Developer |
Billing UX & Edge Cases1d Failed payment/dunning, cancel vs switch-to-free copy, proration. | ||
Cancel / switch-to-free UX1d Confirm copy and flow for Cancel at period end vs Switch to Free; ensure switch-to-free and cancel API usage matches UI (no double cancel). | ||
Review UI copy and API usage; fix any mismatch | 1h | Software Development - Full-stack Developer |
Failed payment / dunning Decide: rely on Stripe dunning only or surface payment failed in UI (e.g. banner when subscription is past_due). If surfacing reflect invoice.payment_failed and subscription status in app. | ||
Implement UI state and/or subscription status for past_due if needed | 2h | Software Development - Full-stack Developer |
Proration and plan switch Confirm proration behavior when switching plans (e.g. create_prorations) is correct and document in runbook or admin doc. | ||
Document proration behavior in runbook | 1h | Software Development - Full-stack Developer |
Testing & Documentation3d Unit tests for Stripe actions and webhook; submit route tests; Stripe setup runbook. | ||
Unit tests – Stripe actions1d Add unit tests for createCheckoutSession createPortalSession updateSubscriptionPrice cancelStripeSubscription pauseStripeSubscription resumeStripeSubscription using Stripe mock or jest mocks. | ||
Add tests for each action with mocked Stripe client1d | 6h | Software Development - Full-stack Developer |
Webhook handler tests1d Tests for webhook route: signature verification (reject invalid accept valid); each event type that updates DB (subscription.deleted → Free; invoice.payment_succeeded / payment_failed → resume/suspend). | ||
Add fixture payloads and tests for verification and event handlers1d | 5h | Software Development - Full-stack Developer |
Stripe setup runbook1d Write runbook: Stripe Dashboard steps (products prices lookup keys) webhook URL and events env vars how to test with Stripe CLI. | ||
Create runbook document in repo or wiki1d | 3h | Software Development - Full-stack Developer |
Submit route test Test submit route: success path (create/update subscription + invoice) validation (missing session_id invalid orgId) idempotency (double submit → no duplicate invoice). | ||
Add submit route tests (success validation idempotency) | 3h | Software Development - Full-stack Developer |
Sign up for Kriyastream to start using this template and many others for your projects.
