Install this Claude Code skill.
Name: Stripe Billing Setup
Save to: ~/.claude/skills/stripe-billing-setup.md

---
---
name: stripe-billing-setup
description: Set up Stripe billing from scratch — products, prices, subscriptions, checkout, webhooks. Use when user says "set up Stripe", "add subscriptions", "integrate payments", or "configure billing".
---

Help the user integrate Stripe billing into their application.

## Instructions

### Step 1: Stripe Account & SDK
- Ensure they have a Stripe account (dashboard.stripe.com)
- Install the SDK for their stack:
  ```bash
  # Node.js
  npm install stripe
  # Python
  pip install stripe
  ```
- Set up env vars:
  ```
  STRIPE_SECRET_KEY=sk_test_...
  STRIPE_PUBLISHABLE_KEY=pk_test_...
  STRIPE_WEBHOOK_SECRET=whsec_...
  ```

### Step 2: Product & Price Catalog
Ask the user about their pricing model:

**Flat-rate subscription:**
```typescript
const product = await stripe.products.create({ name: "Pro Plan" })
const price = await stripe.prices.create({
  product: product.id,
  unit_amount: 2900, // $29.00
  currency: "usd",
  recurring: { interval: "month" },
})
```

**Tiered pricing:**
- Free / Pro / Enterprise
- Create a product for each tier
- Monthly and annual prices for each

**Usage-based:**
```typescript
const price = await stripe.prices.create({
  product: product.id,
  recurring: { interval: "month", usage_type: "metered" },
  billing_scheme: "tiered",
  tiers_mode: "graduated",
  tiers: [
    { up_to: 1000, unit_amount: 0 },      // First 1000 free
    { up_to: 10000, unit_amount: 1 },      // $0.01 each
    { up_to: "inf", unit_amount: 0.5 },    // $0.005 each
  ],
})
```

### Step 3: Checkout Session
Create a checkout flow:
```typescript
const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  payment_method_types: ["card"],
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: "${YOUR_DOMAIN}/billing/success?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: "${YOUR_DOMAIN}/pricing",
  customer_email: user.email,
  metadata: { userId: user.id },
  allow_promotion_codes: true,
  billing_address_collection: "auto",
  tax_id_collection: { enabled: true },
})
```

### Step 4: Webhook Handler
Critical webhook events to handle:

```typescript
// POST /api/stripe/webhook
const event = stripe.webhooks.constructEvent(body, sig, webhookSecret)

switch (event.type) {
  case "checkout.session.completed":
    // Provision access — link Stripe customer to your user
    break
  case "invoice.paid":
    // Renewal succeeded — extend access
    break
  case "invoice.payment_failed":
    // Payment failed — notify user, start grace period
    break
  case "customer.subscription.updated":
    // Plan changed — update user's tier
    break
  case "customer.subscription.deleted":
    // Cancelled — revoke access at period end
    break
}
```

### Step 5: Customer Portal
Let customers manage their own billing:
```typescript
const portalSession = await stripe.billingPortal.sessions.create({
  customer: stripeCustomerId,
  return_url: "${YOUR_DOMAIN}/settings",
})
// Redirect to portalSession.url
```

Configure in Stripe Dashboard → Settings → Customer Portal:
- Allow plan changes
- Allow cancellation (with optional survey)
- Show invoice history
- Allow payment method updates

### Step 6: Database Schema
Store billing state in your database:
```
User
  stripeCustomerId   String?
  stripePriceId      String?
  stripeSubscriptionId String?
  stripeCurrentPeriodEnd DateTime?
  plan               "free" | "pro" | "enterprise"
```

### Step 7: Access Control
```typescript
function hasAccess(user) {
  if (user.plan === "free") return false
  if (!user.stripeCurrentPeriodEnd) return false
  return new Date(user.stripeCurrentPeriodEnd) > new Date()
}
```

### Step 8: Testing Checklist
- [ ] Checkout creates subscription and provisions access
- [ ] Webhook handles invoice.paid (renewal)
- [ ] Webhook handles payment_failed (grace period)
- [ ] Webhook handles subscription.deleted (revoke access)
- [ ] Customer portal allows plan change and cancellation
- [ ] Test with Stripe CLI: `stripe listen --forward-to localhost:3000/api/stripe/webhook`
- [ ] Test cards: 4242424242424242 (success), 4000000000000341 (failure)

### Step 9: Go Live
- [ ] Switch from test to live keys
- [ ] Update webhook endpoint in Stripe Dashboard
- [ ] Enable Stripe Tax if applicable
- [ ] Set up Stripe Radar rules for fraud prevention
- [ ] Configure email receipts and invoices