Billing Endpoints

Subscription and usage billing management.

Get Subscription

GET /billing/subscription

Get current subscription.

curl http://localhost:3000/billing/subscription \
  -H "Authorization: Bearer <token>"

Response:

{
  "id": "sub-123",
  "plan": "pro",
  "status": "active",
  "currentPeriodStart": "2024-01-01T00:00:00Z",
  "currentPeriodEnd": "2024-02-01T00:00:00Z",
  "cancelAtPeriodEnd": false
}

Get Usage

GET /billing/usage

Get current period usage.

curl http://localhost:3000/billing/usage \
  -H "Authorization: Bearer <token>"

Response:

{
  "period": "2024-01",
  "usage": {
    "apiCalls": 15420,
    "apiCallsLimit": 100000,
    "llmTokens": 250000,
    "llmTokensLimit": 1000000,
    "storage": 1073741824,
    "storageLimit": 10737418240
  }
}

Get Invoices

GET /billing/invoices

List invoices.

curl http://localhost:3000/billing/invoices \
  -H "Authorization: Bearer <token>"

Response:

{
  "invoices": [
    {
      "id": "inv-123",
      "amount": 4900,
      "currency": "usd",
      "status": "paid",
      "paidAt": "2024-01-01T00:00:00Z",
      "pdfUrl": "https://..."
    }
  ]
}

Create Checkout

POST /billing/checkout

Create checkout session.

curl -X POST http://localhost:3000/billing/checkout \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "priceId": "price_123",
    "successUrl": "https://app.example.com/success",
    "cancelUrl": "https://app.example.com/cancel"
  }'

Response:

{
  "url": "https://checkout.stripe.com/..."
}

Portal Session

POST /billing/portal

Create customer portal session.

curl -X POST http://localhost:3000/billing/portal \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "returnUrl": "https://app.example.com/settings"
  }'

Response:

{
  "url": "https://billing.stripe.com/..."
}

Cancel Subscription

POST /billing/cancel

Cancel subscription at period end.

curl -X POST http://localhost:3000/billing/cancel \
  -H "Authorization: Bearer <token>"

Response:

{
  "success": true,
  "cancelAt": "2024-02-01T00:00:00Z"
}

Webhooks

POST /billing/webhook

Stripe webhook endpoint.

Configure in Stripe Dashboard:

• Endpoint: https://api.example.com/billing/webhook
• Events: customer.subscription.*, invoice.*

Plans

Configured in config.json:

{
  "billing": {
    "plans": {
      "free": {
        "apiCalls": 1000,
        "llmTokens": 10000,
        "storage": 104857600
      },
      "pro": {
        "apiCalls": 100000,
        "llmTokens": 1000000,
        "storage": 10737418240
      }
    }
  }
}

Tier Enforcement

Usage tracked and enforced:

• API calls counted per request
• LLM tokens tracked per completion
• Storage measured per file

Over-limit responses:

{
  "error": "Usage limit exceeded",
  "message": "API call limit reached for current period",
  "usage": {
    "current": 100001,
    "limit": 100000
  }
}

Status: 402 Payment Required