STRIPE INTEGRATION: Subscriptions + Trials + Usage-Based Billing

→ CORE COMPONENTS (build in this order)
  1. Create customer (idempotent key: customer_id from your DB)
  2. Create subscription (trial 14 days, plan ID from config)
  3. Meter usage (track daily API calls via /v1/meter_events)
  4. Invoice on usage (monthly, calculated from meter events)
  5. Webhook handler (idempotent: check event ID before processing)

→ SUBSCRIPTION FLOW CODE SKELETON
  const subscription = await stripe.subscriptions.create({
    customer: customer_id,
    items: [{ price: 'price_standard_monthly' }],
    trial_period_days: 14,
    trial_settings: { end_behavior: { missing_payment_method: 'cancel' } }
  });
  
  Trap: Always include trial_end_behavior (auto-cancel on failed payment, not force-bill)
  Trap: Store subscription_id in your DB immediately (webhook may fire before create() returns)

→ USAGE METERING (per-customer API calls)
  POST /v1/billing.meter_events
  Payload: { event_name: 'api_calls', customer_id: cust_xxx, quantity: 47, timestamp: now }
  Schedule: Aggregate daily, send once per day (avoid 1000s of small events)
  Idempotence: Use idempotency_key = md5(customer_id + date) (prevents double-counting)

→ WEBHOOK HANDLER (production-critical)
  Events to handle:
    customer.subscription.trial_will_end (14 days in – remind to update payment method)
    invoice.payment_failed (charge failed – mark account, 3-retry window)
    charge.dispute.created (customer dispute – alert team immediately)
  Trap: Process webhooks exactly once – check DB for event_id before acting
  Retry logic: Webhook delivery retry window 24 hours; queue failed webhooks for manual review

→ CUSTOMER PORTAL (self-service)
  Redirect from your app: stripe.billingPortal.sessions.create({ customer_id })
  Users can: Update payment method, view invoices, download receipts, cancel subscription
  Configure: Set cancellation reason categories (allows feedback)

→ DEPLOYMENT CHECKLIST
  ✓ Webhook signing key validated (stripe.webhooks.constructEvent with secret)
  ✓ Idempotent customer creation tested (same email on retry = same customer_id)
  ✓ Trial end edge case: Verify no charge if trial ends without payment method
  ✓ Usage metering: Backfill test customer with dummy events, verify invoice generated
  ✓ Live mode: Start with 5 test customers, verify end-to-end before launch
  ✓ Monitoring: Track webhook latency + failure rate per event type
  Go-live: Start with 10% of signups for 1 week, then 100%