Billing API

Manage Stripe billing programmatically. Checkout and portal endpoints require admin role.

Create Checkout Session

Create a Stripe Checkout session to upgrade to a paid plan.

POST /api/v1/billing/checkout

Authentication: Session (admin role required)

Request body:

{
  "plan": "starter"
}

Response:

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

Redirect the user to the returned URL to complete checkout.

Errors:

Create Portal Session

Create a Stripe Customer Portal session for managing subscriptions, payment methods, and invoices.

POST /api/v1/billing/portal

Authentication: Session (admin role required)

Response:

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

Redirect the user to the returned URL to manage their subscription.

Get Subscription Status

Get the current subscription status for the tenant.

GET /api/v1/billing/status

Authentication: Session or API key

Response:

{
  "data": {
    "plan": "starter",
    "status": "active",
    "current_period_end": "2026-04-23T00:00:00.000Z",
    "cancel_at_period_end": false
  }
}

Stripe Webhook

Receives events from Stripe to sync subscription state. This endpoint is called by Stripe directly — no authentication header required. Stripe signature verification is used instead.

POST /api/v1/billing/webhook

Headers:

Handled events:

• checkout.session.completed — Activate subscription after checkout
• customer.subscription.updated — Sync plan changes
• customer.subscription.deleted — Downgrade to free plan
• invoice.payment_failed — Mark subscription as past due