AI-Assisted Billing

The codebase includes AI-optimized context files and templates that enable AI assistants to implement billing features correctly. This guide explains how to work with AI agents when building billing functionality.

Context Files for AI

The /llms/ directory contains documentation specifically for AI agents:

llms/BILLING.md

Comprehensive billing implementation guide covering:

• UseAutumn + Convex integration patterns
• Feature gating with ctx.check() and ctx.track()
• Subscription vs one-time payment differences
• Common errors and solutions

When working with AI on billing features, reference this file:

"Read llms/BILLING.md and implement subscription tier gating for the dashboard"

llms/templates/billing-*.tsx

Working code templates for common billing scenarios:

• billing-page-gating-template.tsx - Protected routes by subscription
• billing-api-gating-template.ts - API route feature checks
• billing-component-template.tsx - Client billing UI components

These templates follow codebase conventions and are safe to copy.

Effective AI Prompts

Clear and Specific

Reference Context Files

Point AI to relevant context when working on complex features:

"Read llms/BILLING.md and llms/CONVEX.md, then implement usage-based billing
for AI tokens with ctx.track() in the generateText action"

This ensures AI understands both the billing patterns and Convex conventions.

Common AI Workflows

Adding a New Subscription Tier

1. "Add a 'teams' product to autumn.config.ts with 100k API calls and team features"
2. "Push config with npx atmn push"
3. "Update BILLING_PLAN_DETAILS in packages/billing/src/constants.ts"
4. "Add team-specific feature checks to relevant Convex actions"

Implementing Feature Gates

1. "Read llms/BILLING.md"
2. "Add ctx.check() for 'analytics' feature in the dashboard data query"
3. "Show upgrade prompt in the UI if check fails"
4. "Add tests for the feature gate using TestServicesProvider"

Debugging Billing Issues

"Check llms/BILLING.md troubleshooting section and debug why ctx.check()
returns undefined for the dashboard feature"

Validation After AI Changes

Always validate AI-generated billing code:

npx atmn push

// In convex DevTools or test
const result = await ctx.check({ featureId: "your_feature" });
console.log(result.data?.allowed);

pnpm test

Card: 4242 4242 4242 4242
Expiry: 12/34
CVC: 123

Common AI Mistakes

Best Practices with AI

1. Provide Context

Always reference relevant files:

"Read llms/BILLING.md and implement..."

2. Request Tests

Ask for tests alongside features:

"Add subscription upgrade flow with tests using TestServicesProvider"

3. Validate Generated Code

Check that AI code follows patterns:

• Uses userAction for ctx.check()
• Imports from @workspace/* packages
• Includes error handling with AppError
• Has proper TypeScript types

4. Iterate on Errors

If AI code has issues, provide the error message:

"The code fails with 'check is not a function'. Fix by using userAction instead of userMutation"

Templates for AI

Point AI to these templates for quick implementation:

Related Documentation

• Feature Gating - Access control patterns
• Subscriptions - Recurring billing setup
• Usage-Based Billing - Consumption tracking
• Overview - Billing architecture