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

# nora billing

> Workspace billing — state, usage, invoices, overage cap, portal, tax.

Billing surfaces workspace-level financial information from the CLI. Every workspace on a paid plan has these commands; free workspaces show the free-tier state.

## Commands

| Command                   | Description                                     |
| ------------------------- | ----------------------------------------------- |
| `billing state`           | Current subscription snapshot.                  |
| `billing usage`           | Per-meter usage for current period.             |
| `billing history`         | Historical monthly usage.                       |
| `billing invoices`        | All issued invoices.                            |
| `billing portal`          | Print/open provider-hosted customer portal URL. |
| `billing set-overage-cap` | Cap or clear monthly overage.                   |
| `billing open`            | Print/open Nora billing settings URL.           |
| `billing set-tax`         | Set business tax fields.                        |

## `billing state`

```bash theme={null}
nora billing state
```

Prints:

* Plan (Free / Team / Enterprise).
* Subscription status (active / past\_due / canceled).
* Current period (start & end).
* Overage cap (if set).
* Overage used this period.

Add `--json` for machine output.

## `billing usage`

```bash theme={null}
nora billing usage
```

Current billing period usage broken down by meter:

* Model tokens (per provider tier).
* Storage (documents, chunks, vectors).
* Trace volume.
* Any per-plan meters.

Compare against your plan's included quotas.

## `billing history`

```bash theme={null}
nora billing history                                    # last 6 months (default)
nora billing history --from 2026-01-01 --to 2026-06-30  # custom range
```

Monthly usage rollup. Useful for cost analysis and forecasting.

## `billing invoices`

```bash theme={null}
nora billing invoices
```

Lists all invoices ever issued for this workspace:

* Invoice number.
* Period covered.
* Amount.
* Status (paid / open / uncollectible).
* PDF link.

Add `--json` for a script-friendly list.

## `billing portal`

```bash theme={null}
nora billing portal                # prints the URL
nora billing portal --launch       # opens in default browser
```

The customer portal (hosted by our payment provider, Polar) lets you:

* Update payment method.
* View past invoices (with PDFs).
* Update billing email.
* Cancel or change plan.

You'll authenticate on the portal side with the same email as your Nora account.

## `billing set-overage-cap`

```bash theme={null}
# Cap overage at $50/month
nora billing set-overage-cap --cents 5000

# Clear cap (use plan default)
nora billing set-overage-cap --clear
```

Overage cap limits how much you'll be billed above your plan's included quotas. When the cap is hit, further usage is blocked — pending overage-approved requests fail with 402.

* `--cents <n>` — cap in cents (US\$).
* `--clear` — use the plan default (varies by plan).

Only Owners can change this.

## `billing open`

```bash theme={null}
nora billing open                                       # print URL to billing settings
nora billing open --section usage                       # deep-link to usage
nora billing open --section invoices --launch           # open invoices in browser
```

Flags:

* `--section plans|usage|invoices` — which page to link to.
* `--launch` — open in default browser instead of printing.

## `billing set-tax`

```bash theme={null}
nora billing set-tax \
  --business-number "123-45-67890" \
  --tax-email billing@yourcompany.com
```

For Korean workspaces (and similar tax regimes), sets:

* `--business-number` — the tax registration number (사업자등록번호). Pass `""` to clear.
* `--tax-email` — email for tax-invoice delivery.

These fields flow onto your invoices.

## Recipes

### Set an overage cap in a bootstrap script

```bash theme={null}
# $200 monthly overage limit
nora billing set-overage-cap --cents 20000
```

### Monitor spend

```bash theme={null}
# Alert if this month's usage crosses a threshold
usage_cents=$(nora billing usage --json | jq '.total_cents')
[ "$usage_cents" -gt "50000" ] && echo "Warning: >$500 spend this month"
```

### Download all invoice PDFs

```bash theme={null}
mkdir -p invoices
for inv in $(nora billing invoices --json | jq -c '.[]'); do
  url=$(echo "$inv" | jq -r '.pdf_url')
  num=$(echo "$inv" | jq -r '.number')
  curl -sL "$url" -o "invoices/${num}.pdf"
done
```

### Compare usage across workspaces

```bash theme={null}
for ws in acme-dev acme-staging acme-prod; do
  echo "$ws:"
  nora --workspace "$ws" billing usage --json | jq '.total_cents' | \
    awk '{printf "  $%.2f\n", $1/100}'
done
```

## What billing does NOT cover

* **Provider costs** (OpenAI, Anthropic, Google API charges) — billed by the providers directly if you're on BYOK (bring your own key). See [`nora providers`](/cli/providers).
* **Storage attached via BYO buckets** — you pay your S3/R2 provider directly.

Nora billing covers the platform layer: workflow execution, trace storage, retrieval infrastructure, memory, and managed services.

## Related

* [Payments docs](https://nora.my/pricing) — plan details and included quotas.
* [`nora providers`](/cli/providers) — provider API key management (billed by provider).
* [Audit trail](/reliable/versions/audit) — billing-related changes are logged.