Subscription Billing Agent Skill
Stripe subscription lifecycle, plan upgrades/downgrades, usage metering, and billing portal.
The Skill
Full content, every format. Copy it, download it, or install with one command.
---
description: Stripe subscription lifecycle, plan upgrades/downgrades, usage metering, and billing portal.
homepage: https://yepapi.com/skills/subscription-billing
metadata:
tags: [stripe, subscriptions, billing, saas]
---
# Subscription Billing
## Rules
- Stripe Subscriptions API for recurring billing — never build custom recurring charge logic
- Webhook-driven: listen to `customer.subscription.created`, `updated`, `deleted`, `invoice.paid`, `invoice.payment_failed`
- Plan changes: use `stripe.subscriptions.update()` with `proration_behavior: 'create_prorations'` for upgrades/downgrades
- Customer Portal: use Stripe Billing Portal for self-service plan management — `stripe.billingPortal.sessions.create()`
- Usage metering: report usage with `stripe.subscriptionItems.createUsageRecord()` — aggregate locally, report to Stripe hourly or daily
- Trial periods: set `trial_period_days` on the subscription — send reminder email 3 days before trial ends
- Payment failures: handle `invoice.payment_failed` — retry logic is Stripe-managed, update user status after final failure
- Sync plan status: store `subscriptionId`, `planId`, `status`, `currentPeriodEnd` in your database — update on every webhook
## Subscription Sync Pattern
```typescript
// Webhook handler
case "customer.subscription.updated": {
const subscription = event.data.object;
await db.user.update({
where: { stripeCustomerId: subscription.customer },
data: {
plan: subscription.items.data[0].price.lookup_key,
subscriptionStatus: subscription.status,
currentPeriodEnd: new Date(subscription.current_period_end * 1000),
},
});
break;
}
```
## Plan Change Flow
1. User selects new plan in UI
2. Call API route that runs `stripe.subscriptions.update({ items: [{ id, price: newPriceId }] })`
3. Stripe fires `customer.subscription.updated` webhook
4. Webhook handler syncs new plan to database
5. UI reflects new plan on next load
## Avoid
- Trusting client-side plan status — always check database (synced from webhooks)
- Building custom retry logic for failed payments — Stripe handles retries
- Skipping proration on plan changes — users get confused by billing amounts
- Missing `invoice.payment_failed` handler — users stay on paid plan without payingInstall
Why Use the Subscription Billing Skill?
Without this skill, your AI guesses at subscription billing patterns. It might hallucinate deprecated APIs, use outdated conventions, or miss best practices entirely. With it, your AI follows a proven ruleset — every suggestion aligns with current standards.
Drop this skill into your project and your AI instantly knows the rules. Better code suggestions, fewer errors, faster shipping.
Try These Prompts
These prompts work better with the Subscription Billing skill installed. Your AI knows the context and writes code that fits.
"Build a subscription billing system with plan upgrades, downgrades, and proration"
"Create a billing portal with usage metering, invoice history, and payment method management"
"Set up Stripe subscriptions with free trial, grace period, and dunning management"
Works Great With
Subscription Billing skill — FAQ
It covers Stripe subscription lifecycle, plan upgrades/downgrades, usage metering, and billing portal. Your AI builds billing systems that handle edge cases like proration and dunning.
Run `npx skills add YepAPI/skills --skill subscription-billing` in your project root. This copies the skill file into your repo where your AI coding tool can read it automatically.
The skill covers immediate and end-of-period downgrades with Stripe's proration settings. It includes patterns for feature gating based on the new plan and grace periods for data migration.