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

# Billing

> Review plan status, usage, seats, and invoices for your organization

Billing covers the organization plan, governed-action usage, seats, invoices, and payment methods. Alerts for past due, limit reached, and scheduled plan changes appear in the dashboard only.

## Overview

Dome meters governed actions from the durable audit trail. Plans include a permanent free SKU and paid tiers with usage caps and platform fees. SIEM streaming and other add-on capabilities depend on plan entitlements.

The typical workflow is:

1. [Check status and usage](#check-status-and-usage) for the active plan and current period.
2. [Change plan or seats](#change-plan-or-seats) when you need a different SKU or seat count.
3. [Manage payment methods and invoices](#manage-payment-methods-and-invoices) for collection.

Card capture completes in the dashboard (or Stripe.js). The CLI can list methods and start setup, but it is not a full card-entry path.

## Requirements

Before you begin:

* Authenticate to Dome with an organization-scoped role that can manage billing
* Use the dashboard for payment-method capture and billing alert banners

### Permissions

| Default roles               | Permission       | Grants                                                               |
| --------------------------- | ---------------- | -------------------------------------------------------------------- |
| Organization billing admins | `billing.manage` | Status, plans, usage, seats, invoices, plan changes, payment methods |

## Check status and usage

Read the active plan, period usage, and free-tier caps when they apply.

<Callout icon="key">Requires `billing.manage`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome billing status
    dome billing plans
    dome billing usage
    dome usage-caps
    ```

    `dome usage-caps` is read-only and returns empty for paid orgs.

    <Callout icon="terminal">Reference: [`dome billing`](/cli/manage/billing)</Callout>
  </Tab>

  <Tab title="Dashboard">
    Open **Billing** in the organization settings. Status, usage, and limit banners appear on the billing page and across the dashboard when alerts fire.
  </Tab>
</Tabs>

## Change plan or seats

Change the SKU or seat count for the organization. Use `--dry-run` to preview.

<Callout icon="key">Requires `billing.manage`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome billing change-plan <sku> --interval monthly --seats 5 --dry-run
    dome billing change-plan <sku> --interval monthly --seats 5
    dome billing seats
    dome billing cancel --yes
    ```

    <Callout icon="terminal">Reference: [`dome billing change-plan`](/cli/manage/billing#change-plan)</Callout>
  </Tab>

  <Tab title="Dashboard">
    Use the billing page to select a plan, adjust seats, or cancel. Scheduled downgrades and limit alerts surface as dashboard banners.
  </Tab>
</Tabs>

## Manage payment methods and invoices

List invoices and payment methods. Add a card through the dashboard.

<Callout icon="key">Requires `billing.manage`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome billing invoices
    dome billing payment-methods
    dome billing contact
    dome billing contact set --email billing@example.com
    ```

    <Callout icon="terminal">Reference: [`dome billing invoices`](/cli/manage/billing#invoices)</Callout>
  </Tab>

  <Tab title="Dashboard">
    Add or replace payment methods and download invoices from the billing page. Billing alerts (past due, org lock, limit reached, scheduled downgrade) are dashboard-only.
  </Tab>
</Tabs>

## Org lock and plan limits

Every org member sees a read-only lock banner when the organization is suspended for billing reasons. Enterprise orgs are never locked for billing.

| Deny reason             | Meaning                                  | Recovery                                       |
| ----------------------- | ---------------------------------------- | ---------------------------------------------- |
| `trial_expired`         | Free trial ended without a paid plan     | Add a payment method and switch to a paid plan |
| `billing_locked`        | Paid plan is in dunning (failed charges) | Update the payment method                      |
| `subscription_canceled` | Paid plan canceled and reverted to Free  | Choose a plan on the billing page              |
| `org_suspended`         | Org is locked from mutating operations   | Resolve the underlying billing state           |

Upgrades apply on the next request. Downgrades and cancellations keep the current plan until the period ends, then the org moves to the target SKU.

Downgrading may put existing assets — extra tenants, workspaces, seats, agents, or connections — over the target plan's caps. The dashboard blocks the switch and lists the over-limit resources; remove them first, then retry. Creates that hit a SKU cap return HTTP 429 and emit `access.denied` with `reason=quota_exceeded` (see [access.denied reasons](/operate/audit#access-denied-reasons)). Use `dome usage-caps` to inspect free-tier caps when they apply.

## Next steps

* [Export data](/manage/export#stream-audit-evidence-to-a-siem) for continuous SIEM streaming when your plan includes it
* [Set usage limits](/govern/quotas) for workspace Quotas (runtime spend caps, separate from plan metering)
* [Manage access](/manage/access) for who can administer the organization