> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Plans & Billing

> Operate local licenses and conditional subscription workflows without treating billing metadata as current access enforcement.

The Admin **Plans & Billing** page presents the billing path available to the deployment. Self-hosted deployments can use a locally verified license, while connected self-hosted and multi-tenant deployments can expose subscription operations when their billing service is configured.

In the current source, license-enforcement and tier-gate middleware are compatibility pass-throughs. License and subscription status can be verified, cached, and displayed, but they do not currently block application routes or features. Reconfirm the behavior of the running version before treating billing state as an access-control or entitlement contract.

## What the page represents

| Surface                             | Current purpose                                                                        | Not established by this surface                  |
| ----------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------ |
| Plan label and subscription summary | Displays available billing metadata for the active deployment                          | A published price or feature-entitlement catalog |
| Local license status                | Displays verified license metadata, expiration state, seat values, and refresh results | Current route or feature enforcement             |
| Checkout, portal, and seat actions  | Starts configured billing-service operations for an Admin                              | Availability when billing connectivity is absent |
| Trial action                        | Ends a trial only in the supported multi-tenant path                                   | A self-hosted license lifecycle operation        |

The repository includes plan labels in the UI, but this documentation does not define prices or infer feature access from those labels.

## Deployment paths

| Deployment path                   | Source of billing state                                     | Available operations                                                                                         |
| --------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Self-hosted with a manual license | A signed license uploaded and verified locally              | Upload, inspect status, refresh local cache, or delete the local license through Admin controls when exposed |
| Connected self-hosted             | Billing service plus a locally claimed and verified license | Checkout, return-time claim, billing summary, portal, seat update, and license refresh when configured       |
| Multi-tenant                      | The tenant's configured billing service                     | Billing summary, checkout, portal, seat update, and supported trial completion when configured               |

The page chooses between self-hosted and multi-tenant service routes according to deployment configuration. Do not copy an operation from one path into another without verifying that condition.

## Local license lifecycle

#### Obtain the license through an approved channel

A self-hosted operator obtains the deployment-specific signed license through its established commercial or internal process. Keep the license out of tickets, chat transcripts, and documentation.

#### Claim or upload as an Admin

A connected deployment can claim a license after checkout. A disconnected or air-gapped deployment can use the manual upload control when that self-hosted endpoint is available.

#### Verify before persistence

The backend verifies the signed payload with its configured RSA-PSS and SHA-256 verification path before saving it. A failed signature must not create active local license state.

#### Read local status

The page can show plan metadata, seats, expiration, grace, or gated status derived from the verified license and cached metadata. These values are operational status in the current source, not route enforcement.

Manual upload is a self-hosted operation. It does not require a live billing request at upload time, but future connected refresh or subscription changes still require the relevant service path.

## Connected billing lifecycle

#### Start checkout

An Admin starts a configured checkout session. A new self-hosted purchase can begin without an existing license; a renewal identifies the existing deployment through its current license or tenant context.

#### Process the return

After a successful self-hosted return, the UI claims the signed license, retries while issuance is pending, refreshes application settings, and then reloads billing status.

#### Manage the subscription

Portal and seat controls use the configured billing service. A self-hosted portal operation requires an existing local license, and a seat decrease cannot be lower than seats already in use.

#### Refresh local state

After a connected self-hosted seat update, reclaim or refresh the regenerated license before relying on the displayed seat values.

These operations are conditional on the billing service or control-plane connection configured for the deployment. They are not an offline fallback for manual-license environments.

## Conditional operations

| Operation             | Required condition                                                                           | Failure boundary                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Checkout              | Admin access and configured billing connectivity                                             | No checkout session is available when the billing service cannot be reached or is not configured. |
| Billing summary       | A valid tenant context, or the self-hosted license context when required                     | A self-hosted deployment with no license can return an empty subscription state.                  |
| Billing portal        | Admin access, configured connectivity, and an existing tenant or self-hosted license context | Missing context or service failure prevents portal creation.                                      |
| Seat update           | Admin access, configured connectivity, and a requested count not below current use           | Validation or service failure leaves the requested change unapplied.                              |
| End trial             | Multi-tenant mode, configured connectivity, and the required payment method                  | This operation is not provided as a self-hosted license action.                                   |
| Manual license upload | Self-hosted mode and a valid signed license payload                                          | Invalid format or signature is rejected before active local state is stored.                      |

## Current access behavior

| State                                         | Current observable behavior                                          | Governance conclusion                                                             |
| --------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Active, grace, gated, or expired local status | Status and metadata can be calculated and displayed                  | Record and monitor the state, but do not claim it currently blocks routes.        |
| Plan or tier label                            | The UI can display the label supplied by billing or license metadata | Do not infer a price or enabled feature list from the label.                      |
| License middleware                            | Allows requests through in the current implementation                | Preserve application authorization controls independently of billing state.       |
| Tier checks                                   | Resolve as allowed in the current implementation                     | Validate feature exposure directly rather than relying on a plan-name comparison. |

Billing state is not a substitute for Admin authorization, tenant isolation, group permissions, connector access, or model-provider controls.

## Disconnected and failure behavior

A valid manually uploaded self-hosted license can continue to provide locally readable metadata without a live billing call. Connected checkout, portal, seat, claim, and refresh operations can still fail because of configuration, network, or billing-service availability. Billing-summary reads may return an empty or temporarily unavailable state rather than proving that a subscription was canceled.

Keep signed license payloads and billing identifiers out of logs, screenshots, and documentation. Record operation time, deployment path, response status, and a non-sensitive correlation identifier when investigating a failure.

## Verify

1. Confirm whether the deployment is self-hosted or multi-tenant and whether billing connectivity is intentionally configured.
2. As an Admin, verify that the page uses the matching service path and does not expose operations belonging only to the other deployment path.
3. For a manual license, test a valid signed payload and a deliberately invalid test payload; confirm that only the valid payload creates readable local status.
4. For connected self-hosted checkout, confirm the return-time claim and settings refresh before accepting the displayed subscription or seat state.
5. Test an application route independently of billing state and confirm the running version's enforcement behavior rather than inferring it from the page label.

## Related pages

* [Deployment Modes](/opencore/deployment-modes) explains the operational differences between supported modes.
* [Users, Groups & Roles](/opencore/governance/users-and-groups) describes the Admin boundary for organization controls.
* [Usage, Identity & Security](/opencore/governance/usage-and-security) explains the controls that remain independent of billing metadata.