Billing Endpoints Guide

When to Use This Skill

• Debugging billing issues (double charges, missing invoices, wrong subscription items)
• Adding new billing endpoints
• Understanding how Autumn state maps to Stripe
• Fixing subscription update/cancel/attach flows
• Working with subscription schedules (future changes)

Endpoint Quick Reference

All new billing endpoints MUST use V2 architecture.

V2 Architecture: The 4-Layer Pattern

Every V2 billing endpoint follows this exact pattern. Copy this template:

// From: billing/v2/updateSubscription/handleUpdateSubscription.ts

export const handleUpdateSubscription = createRoute({
  body: UpdateSubscriptionV0ParamsSchema,
  handler: async (c) => {
    const ctx = c.get("ctx");
    const body = c.req.valid("json");

    // 1. SETUP - Fetch all context needed for billing operation
    const billingContext = await setupUpdateSubscriptionBillingContext({
      ctx,
      params: body,
    });
    logUpdateSubscriptionContext({ ctx, billingContext });

    // 2. COMPUTE - Determine Autumn state changes
    const autumnBillingPlan = await computeUpdateSubscriptionPlan({
      ctx,
      billingContext,
      params: body,
    });
    logUpdateSubscriptionPlan({ ctx, plan: autumnBillingPlan, billingContext });

    // 3. ERROR HANDLING - Validate before execution
    await handleUpdateSubscriptionErrors({
      ctx,
      billingContext,
      autumnBillingPlan,
      params: body,
    });

    // 4. EVALUATE - Map Autumn changes to Stripe changes (UNIFIED)
    const stripeBillingPlan = await evaluateStripeBillingPlan({
      ctx,
      billingContext,
      autumnBillingPlan,
    });
    logStripeBillingPlan({ ctx, stripeBillingPlan, billingContext });

    // 5. EXECUTE - Run Stripe actions, then Autumn DB updates
    const billingResult = await executeBillingPlan({
      ctx,
      billingContext,
      billingPlan: {
        autumn: autumnBillingPlan,
        stripe: stripeBillingPlan,
      },
    });

    const response = billingResultToResponse({ billingContext, billingResult });
    return c.json(response, 200);
  },
});

Key principle: evaluateStripeBillingPlan and executeBillingPlan are UNIFIED across all endpoints. Rarely modify them.

See V2 Four-Layer Pattern Deep Dive for detailed explanation.

Two Critical Stripe Mappings

Getting billing right means getting these two mappings right:

1. Subscription Items (Immediate Changes)

When: Updating a subscription right now (add/remove/change items immediately)

Key function: buildStripeSubscriptionItemsUpdate

Flow:

FullCusProduct[] 
  → filter by subscription ID
  → filter by active statuses  
  → customerProductToStripeItemSpecs() 
  → diff against current subscription
  → Stripe.SubscriptionUpdateParams.Item[]

See Stripe Subscription Items Reference for details.

2. Schedule Phases (Future Changes)

When: Scheduling changes for the future (downgrades at cycle end, scheduled cancellations)

Key function: buildStripePhasesUpdate

Flow:

FullCusProduct[]
  → normalize timestamps to seconds
  → buildTransitionPoints() (find all start/end times)
  → for each period: filter active products
  → customerProductsToPhaseItems()
  → Stripe.SubscriptionScheduleUpdateParams.Phase[]

Test reference: tests/unit/billing/stripe/subscription-schedules/build-schedule-phases.spec.ts

See Stripe Schedule Phases Reference for details.

Stripe Invoice Decision Tree

Critical: Stripe sometimes forces invoice creation. If you also create a manual invoice, customer gets double-charged.

Does Stripe force-create an invoice?
├── Creating a new subscription? 
│   └── YES → Stripe creates invoice. DO NOT create manual invoice.
│
├── Removing trial from subscription? (isTrialing && !willBeTrialing)
│   └── YES → Stripe creates invoice. DO NOT create manual invoice.
│
└── Otherwise
    └── NO → We create manual invoice using buildStripeInvoiceAction()

Key functions: - shouldCreateManualStripeInvoice() - Returns true if WE should create invoice - willStripeSubscriptionUpdateCreateInvoice() - Returns true if STRIPE will create invoice

See Stripe Invoice Rules Reference for full decision tree.

Common Issues & Fixes

See Common Bugs Reference for detailed debugging steps.

Adding a New Billing Endpoint

1. Create setup function: setup/setupXxxBillingContext.ts - Extend BillingContext interface if needed - Fetch customer, products, Stripe state, timestamps

2. Create compute function: compute/computeXxxPlan.ts - Return AutumnBillingPlan with insertCustomerProducts, deleteCustomerProduct, lineItems

3. Create error handler: errors/handleXxxErrors.ts - Validate before execution

4. Wire up handler: handleXxx.ts - Use the 4-layer template above

5. DO NOT modify evaluateStripeBillingPlan or executeBillingPlan unless absolutely necessary

See V2 Four-Layer Pattern for detailed guidance.

Invoicing Utilities (Pure Calculations)

The shared/utils/billingUtils/ folder contains pure calculation functions that determine what customers are charged. These are the foundation of all billing operations.

Key utilities:

Key concepts: - LineItem.amount is positive for charges, negative for refunds - context.direction controls the sign ("charge" vs "refund") - Proration is applied automatically when billingPeriod is provided - Consumable prices don't prorate (usage is charged as-is)

See Invoicing Utilities Reference for detailed documentation.

Key File Locations

V2 Billing (server/src/internal/billing/v2/)

Stripe Mapping Utilities

Types

Invoicing Utilities (shared/utils/billingUtils/)

Tests

Reference Files

Load these on-demand for detailed information:

• V2 Four-Layer Pattern - Deep dive on each layer
• Stripe Subscription Items - Immediate changes mapping
• Stripe Schedule Phases - Future changes mapping
• Stripe Invoice Rules - Invoice decision tree
• Invoicing Utilities - Pure calculation functions for charges
• Common Bugs - Debugging guide with solutions