Billing API

The Billing API provides a complete Stripe integration for managing subscriptions, metered usage, and customer billing portals.

Authentication

All billing endpoints require authentication. Include your session token in the request headers:

Authorization: Bearer <session_token>

Base URL

/api/billing

Endpoints Overview

Response Format

All responses follow a consistent JSON structure:

{
  "success": true,
  "data": { ... },
  "error": null
}

Error responses:

{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Error Codes

Webhook Events

The billing system listens to Stripe webhooks for:

• checkout.session.completed - Subscription created
• invoice.payment_succeeded - Payment received
• invoice.payment_failed - Payment failed
• customer.subscription.updated - Subscription changed
• customer.subscription.deleted - Subscription cancelled

Rate Limits

• 100 requests per minute per user
• 1000 requests per hour per organization

SDK Example

import { createBillingClient } from '@/lib/billing/client';

const billing = createBillingClient();

// Get subscription status
const subscription = await billing.getSubscription();

// Create checkout session
const session = await billing.createCheckout({
  priceId: 'price_123',
  successUrl: '/dashboard?success=true',
  cancelUrl: '/pricing?canceled=true'
});