Skip to main content

​
Subscriptions and Plan Lifecycle

Use these endpoints to manage workspace subscription state and customer portal access.

​
Endpoints

  • GET /api/billing/plans
  • GET /api/billing/:workspaceId
  • POST /api/billing/:workspaceId/subscribe
  • POST /api/billing/:workspaceId/change-plan
  • POST /api/billing/:workspaceId/cancel
  • POST /api/billing/:workspaceId/reactivate
  • GET /api/billing/:workspaceId/portal

​
Auth and permissions

All billing routes are session-authenticated.
  • billing:read: plan and billing reads
  • billing:manage: subscribe/change/cancel/reactivate/portal

​
Subscribe

POST /api/billing/:workspaceId/subscribe 
{
  "plan": "pro",
  "period": "monthly"
}
Rules:
  • Allowed subscribe targets: plus, pro, agency.
  • Creates Stripe checkout session URL.
  • Uses workspace/user context to create or reuse Stripe customer.

​
Change plan

POST /api/billing/:workspaceId/change-plan 
{
  "plan": "agency",
  "period": "yearly"
}
Behavior:
  • Supports transition across starter, plus, pro, agency.
  • Same-plan requests are rejected.
  • Transition to starter cancels paid subscription at cycle end.
  • Paid-plan changes update Stripe subscription.

​
Cancel and reactivate

  • POST /api/billing/:workspaceId/cancel
  • POST /api/billing/:workspaceId/reactivate
Cancel behavior:
  • Requires active Stripe subscription.
  • Cancels at period end and returns effective date.
Reactivate behavior:
  • Removes scheduled cancellation if still reactivatable.
  • Returns normalized success message.

​
Portal

GET /api/billing/:workspaceId/portal Returns customer portal URL for payment-method and invoice management.

​
Billing info response (GET /api/billing/:workspaceId)

Returns a composite billing object with:
  • current plan and period
  • credits balance/included/purchased/used values
  • billing cycle dates
  • subscription status fields
  • plan limits used by dashboard

​
Common errors

  • 400: invalid plan/period, same-plan transition, no subscription for requested action
  • 403: missing permission
  • 404: workspace/user not found
  • 500: provider integration failure (STRIPE_ERROR)