Agent skill · software engineering · alirezarezvani
stripe-integration-expert
Use for any Stripe integration: subscriptions, trials, proration, checkout, usage billing, webhooks, customer portal or invoicing in Next.js, Express or Django. Writes idempotent webhook handlers and debugs delivery failures.
Why this skill is useful
Adds executable scripts and detailed integration patterns for Stripe that are not commonly found in public documentation.
What it needs
Requires stripe-cli installed locally. Requires stripe account access. About 6k tokens when loaded. Last updated 2026-08-05. 23,939 stars on the source repository.
What this skill does
Stripe Integration Expert Tier: POWERFUL Category: Engineering Team Domain: Payments / Billing Infrastructure --- Overview Implement production-grade Stripe integrations: subscriptions with trials and proration, one-time payments, usage-based billing, checkout sessions, idempotent webhook handlers, customer portal, and invoicing. Covers Next.js, Express, and Django patterns. --- Core Capabilities Subscription lifecycle management (create, upgrade, downgrade, cancel, pause) Trial handling and conversion tracking Proration calculation and credit application Usage-based billing with metered pricing Idempotent webhook handlers with signature verification Customer portal integration Invoice generation and PDF access Full Stripe CLI local testing setup --- When to Use Adding subscription billing to any web app Implementing plan upgrades/downgrades with proration Building usage-based or seat-based billing Debugging webhook delivery failures Migrating from one billing model to another --- Subscription Lifecycle State Machine DB subscription status values: trialing active pastdue canceled cancelpending paused unpaid --- Stripe Client Setup --- Checkout Session (Next.js App Router) --- Subscription Upgrade/Downgrade --- Complete Webhook Handler (Idempotent) --- Usage-Based Billing --- Customer Portal --- Testing with Stripe CLI --- Feature Gating Helper --- Common Pitfalls Webhook delivery order not guaranteed — always re-fetch from Stripe API, never trust event data alone for DB updates Double-processing webhooks — Stripe retries on 500; always use idempotency table Trial conversion tracking — store hasHadTrial: true in DB to prevent trial abuse Proration surprises — always preview proration before upgrade; show user the amount before confirming Customer portal not configured — must enable features in Stripe dashboard under Billing → Customer portal settings Missing metadata on checkout — always pass userId in metadata; can't link subscription to user without it
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills alirezarezvani/stripe-integration-expert--adec52