Stripe Sandbox Setup: Usage-Based Billing for AI SaaS

[c9r]

🚀 Stripe Sandbox Configuration Summary

Successfully configured a test Stripe account for usage-based billing suitable for an AI SaaS platform.

✅ What Was Completed

1. Products Created

• prod_SyK9qt885gLUbc - "Claude API Pro" (main product)
• prod_SyKA9GFTn7Vza6 - "Claude API Pro - Monthly Base" (platform fee)
• prod_SyKBD4NfwWNUny - "Claude API Pro - Token Usage" (metered usage)

2. Pricing Plans Configured

• pro_monthly_base - $49.00/month recurring base fee
• pro_overage - $0.002 per 1K tokens (usage-based)

3. Test Customer Setup

• Customer: Acme AI Corp (cus_SyKBAurM5GKlpW)
• Email: billing@acme-ai.com
• Payment Method: Test Visa card attached

4. Test Transactions

• Created 3 successful test charges totaling $770.50
• Demonstrated payment failure scenarios (declined, insufficient funds, fraud detection)
• Processed partial refund of $20.00
• Current pending balance: $727.26

5. Billing Architecture

Established a two-tier pricing model:

• Base Monthly Fee: Fixed platform access charge
• Usage-Based Pricing: Pay-per-token consumption model

📊 Pricing Structure

Monthly Invoice Example:
- Base Platform Fee: $49.00
- Token Usage (2.5M): $5.00 (2,500 × $0.002)
- Total: $54.00

🔧 Technical Implementation Notes

• API Version: Stripe API 2025-08-27.basil
• Test Mode: All operations in sandbox environment
• Architecture: Products → Prices → Subscriptions → Usage Tracking

💡 Key Learnings

1. Metered Billing Evolution: Stripe now requires Billing Meters API for true metered usage (as of 2025-03-31)
2. Products vs Prices: One product can have multiple pricing strategies
3. Usage Tracking: Can be implemented via invoice items or the new Billing Meters API
4. Subscription Structure: Base fee + usage components work well for SaaS models

[c9r]

🔄 What Remains To Be Done

1. Billing Meters API Implementation 🎆

Stripe now requires the Billing Meters API for true metered usage (as of 2025-03-31). Need to:

• Create a proper billing meter with aggregation rules
• Configure customer mapping for automatic association
• Set up event reporting pipeline
• Implement webhook handlers for usage events

2. Active Subscription Creation 📈

Current setup has products and prices but no active subscriptions:

• Create subscription with both base fee and usage components
• Configure proper billing cycle anchoring
• Set up trial periods if needed
• Test subscription lifecycle events

3. Usage Tracking Infrastructure 📡

// Need to implement:
- Real-time token counting
- Usage aggregation service
- Batch reporting to Stripe
- Usage analytics dashboard

4. Tiered Pricing Implementation 📊

Implement volume discounts for enterprise customers:

• 0-100K tokens: $0.003/1K
• 100K-1M tokens: $0.002/1K
• 1M+ tokens: $0.001/1K

5. Customer Portal Integration 🌐

• Enable Stripe Customer Portal
• Configure self-service options
• Add usage visualization
• Implement spending limits/alerts

6. Webhook Handling 🤝

• Set up webhook endpoints
• Handle subscription lifecycle events
• Process payment failures gracefully
• Implement retry logic

7. Production Considerations ⚠️

• API key security (environment variables)
• Error handling and logging
• Rate limiting
• Idempotency keys for critical operations
• PCI compliance considerations

8. Testing Suite 🧪

• Unit tests for billing calculations
• Integration tests with Stripe API
• Load testing for usage reporting
• Failure scenario testing

9. Documentation 📖

• API documentation for usage reporting
• Customer onboarding guide
• Billing FAQ
• Integration examples

10. Migration Path 🔄

• Plan migration from test to production
• Data migration strategy
• Gradual rollout plan
• Rollback procedures

Next Immediate Steps:

1. ✅ Implement Billing Meters API correctly
2. ✅ Create an active subscription for test customer
3. ✅ Build usage reporting endpoint
4. ✅ Set up basic webhook handler
5. ✅ Create simple usage dashboard

Code Example for Usage Reporting:

// Usage reporting endpoint
app.post('/api/usage/report', async (req, res) => {
  const { customerId, tokens } = req.body;
  
  try {
    // Report to Stripe Billing Meter
    await stripe.billing.meterEvents.create({
      event_name: 'api_tokens_consumed',
      payload: {
        stripe_customer_id: customerId,
        value: Math.ceil(tokens / 1000)
      },
      timestamp: Math.floor(Date.now() / 1000)
    });
    
    res.json({ success: true });
  } catch (error) {
    console.error('Usage reporting failed:', error);
    res.status(500).json({ error: 'Failed to report usage' });
  }
});

Estimated Timeline:

• Week 1: Billing Meters API + Active Subscriptions
• Week 2: Usage Tracking + Webhooks
• Week 3: Customer Portal + Testing
• Week 4: Documentation + Production Prep

---

This setup provides a solid foundation, but production readiness requires completing these remaining tasks.