> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linquid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions and Plan Lifecycle

> Plan catalog, subscribe, change-plan, cancel/reactivate, and billing portal endpoints

# 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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`)