antigravity-superpowers: Skill for Claude Code

Subscription Billing Lens

Philosophy: Billing is load-bearing infrastructure. A bug in billing = lost revenue or incorrect charges. Build it like critical path code: idempotent, webhook-driven, logged exhaustively.

---

Core Instincts

• Webhook-first — Stripe's webhook is the source of truth, not your API response
• Idempotency everywhere — billing operations must be safe to retry
• Never trust client state for billing — always fetch subscription status from Stripe server-side
• All clock-sensitive operations use event.created — not Date.now()
• Soft failures, never hard block — grace period on payment failures protects revenue

---

Stripe Integration Architecture

User upgrades plan →
  1. Client: Stripe.js → Payment Method → PaymentIntent / SetupIntent
  2. Server: Create/Update Subscription on Stripe
  3. Stripe: Processes payment → emits webhook event
  4. Server: Webhook handler updates DB subscription status
  5. Server: Return state from DB (never from Stripe API response)

⚠️ Anti-pattern: updating DB from API response
✅ Pattern: update DB only from webhook confirmation

---

Critical Webhook Events to Handle

Event	What to do
checkout.session.completed	Provision access, send welcome email
customer.subscription.created	Set status = active, log
customer.subscription.updated	Update plan, seats, feature flags
customer.subscription.deleted	Set status = canceled, begin grace period
invoice.payment_succeeded	Extend access, reset dunning state
invoice.payment_failed	Start dunning, notify user, DON'T revoke access immediately
invoice.upcoming	Warn user of upcoming charge
customer.subscription.trial_will_end	3-day warning email before trial ends

---

Trial Logic Rules

Trial best practices:
- Default trial: 14 days (Stripe default is 30; reduce for faster conversion signal)
- Require payment method at trial start (reduces churn at trial end)
- Free trial without CC = high trial-end churn; use for virality, not conversion
- trial_will_end webhook fires 3 days before → trigger upgrade prompt

Trial states:
  trialing → (payment method on file) → auto-converts to active
  trialing → (no payment method) → needs_payment_method → upgrade prompt