agent-11: Skill for Claude Code

SaaS Billing & Subscription Management

Capability

Implement subscription lifecycle management, plan enforcement, usage tracking, and billing operations. Covers trial periods, plan changes, quota enforcement, and subscription status synchronization with payment providers.

Use Cases

• Trial period management with conversion tracking
• Plan upgrades and downgrades with proration
• Usage quota tracking and enforcement
• Subscription status webhooks handling
• Billing history and invoice access
• Failed payment recovery (dunning)

Patterns

Plan Definition & Enforcement

When to use: Enforce feature access and limits based on subscription tier

Implementation: Define plans with features and limits, check against current subscription.

// Plan definitions
const PLANS = {
  free: {
    id: 'free',
    name: 'Free',
    price: 0,
    limits: {
      projects: 3,
      teamMembers: 1,
      storageGb: 1,
      apiRequestsPerMonth: 1000
    },
    features: ['basic_analytics']
  },
  pro: {
    id: 'pro',
    name: 'Pro',
    stripePriceId: 'price_pro_monthly',
    price: 29,
    limits: {
      projects: 25,
      teamMembers: 10,
      storageGb: 50,
      apiRequestsPerMonth: 50000
    },
    features: ['basic_analytics', 'advanced_analytics', 'api_access', 'priority_support']
  },
  enterprise: {
    id: 'enterprise',
    name: 'Enterprise',
    stripePriceId: 'price_enterprise_monthly',
    price: 99,
    limits: {
      projects: -1, // unlimited
      teamMembers: -1,
      storageGb: 500,
      apiRequestsPerMonth: -1
    },
    features: ['basic_analytics', 'advanced_analytics', 'api_access', 'priority_support', 'sso', 'audit_logs', 'custom_integrations']
  }
} as const;

// Check feature access
function hasFeature(orgPlan: string, feature: string): boolean {
  const plan = PLANS[orgPlan];
  return plan?.features.includes(feature) ?? false;
}

// Check limit
function checkLimit(orgPlan: string, resource: string, current: number): boolean {
  const plan = PLANS[orgPlan];
  const limit = plan?.limits[resource];
  if (limit === -1) return true; // unlimited
  return current < limit;
}

// Middleware for feature gating
async function requireFeature(feature: string) {
  return async (req: Request, next: NextFunction) => {
    const org = req.tenant;
    if (!hasFeature(org.plan, feature)) {
      throw new PaymentRequiredError(
        `Upgrade to access ${feature}`,
        { requiredPlan: getMinimumPlanForFeature(feature) }
      );
    }
    return next();
  };
}