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

# Billing

> Plans, included quotas, on-demand tokens, the Customer Portal, and how to size your subscription.

Agnes is billed on a Stripe subscription with a **monthly token
quota** plus **on-demand overage** on paid tiers. Sandbox traffic
(`ak_test_*`) is always free.

This page covers the plan structure, the billing portal, and how to
right-size a subscription. The wire-level error semantics live on
[`billing_required`](/errors/billing_required) and
[`billing_grace_period`](/errors/billing_grace_period).

## Plan tiers

| Tier             | Included tokens / month | On-demand overage | Best for                                     |
| ---------------- | ----------------------- | ----------------- | -------------------------------------------- |
| **Trial**        | 100,000                 | —                 | New tenants getting started.                 |
| **Starter**      | 5,000,000               | Yes               | Small / new production deployments.          |
| **Professional** | 60,000,000              | Yes               | Mid-size production deployments.             |
| **Enterprise**   | 100,000,000             | Yes               | High-volume + custom limits, support, terms. |

The included token bucket resets monthly on your subscription
anniversary. On-demand overage tokens are billed at the published
per-million rate via a Stripe **metered subscription item**; they
appear on the next invoice rather than charging your card per call.

For the **current per-token rate** and any contract-specific pricing,
see your in-app billing page at
[`agnes.lasscyber.com/agnes-info/billing`](https://agnes.lasscyber.com/agnes-info/billing)
or contact [`sales@lasscyber.com`](mailto:sales@lasscyber.com). We
intentionally do not publish per-token rates here because they evolve
faster than this docs site does.

## What counts as a token

Each `analyze` call charges tokens roughly proportional to the input
length plus a per-analyzer base cost. The per-tenant **usage summary**
endpoint
(`GET /api/v1/billing/usage` and the dashboard chart) attributes
tokens to:

* `input_tokens` — your prompt's token count.
* `analyzer_tokens` — fixed per-analyzer overhead.
* `output_tokens` — Agnes's structured response (small).

The endpoints that **do not** charge tokens:

* Health endpoints (`/health`, `/healthz`).
* Read endpoints (`GET`s on policies, rules, keys).
* The Stripe webhook.
* Sandbox traffic.

## Subscribing

1. Sign in at
   [`agnes.lasscyber.com/agnes-info/billing`](https://agnes.lasscyber.com/agnes-info/billing).
2. Pick a plan. The dashboard launches a Stripe Checkout session.
3. Enter payment details and confirm. Your tenant is upgraded as soon
   as Stripe reports the subscription `active`.

Required scopes: `billing:subscribe`, `billing:plan_change`,
`billing:payment_methods_update`. Owners and admins have them;
members do not.

## Managing the subscription

The **Customer Portal** is the canonical place to:

* Update the payment method on file.
* Pay outstanding invoices.
* Switch plans.
* Cancel or resume the subscription.
* Download invoice PDFs.

The dashboard's **Manage billing** button opens the portal in a
Stripe-hosted session. Programmatic access:

```bash theme={null}
curl -X POST https://api.lasscyber.com/api/v1/billing/portal-session \
  -H "Authorization: Bearer ak_…" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://agnes.lasscyber.com/agnes-info/billing"}'
```

Returns `{ "url": "https://billing.stripe.com/..." }` — redirect the
user there.

## Right-sizing your subscription

Three signals to watch:

1. **Token usage.** The dashboard chart at
   [`agnes.lasscyber.com/agnes-info/billing`](https://agnes.lasscyber.com/agnes-info/billing)
   shows daily token spend over the trailing 30 days. If you are
   consistently at 60–80% of your included bucket, you are at the
   right tier; consistently above 100% means an on-demand bill is
   coming.
2. **On-demand spend.** If on-demand consistently exceeds the
   marginal price difference between your tier and the next, upgrading
   is cheaper.
3. **Rate limits.** If you regularly see 429s
   ([`rate_limit_exceeded`](/errors/rate_limit_exceeded)) the tier-level
   request rate is the constraint, not the token bucket. Upgrading lifts
   that ceiling too.

For Enterprise contracts, custom token buckets and rate-limit floors
are available. Email
[`sales@lasscyber.com`](mailto:sales@lasscyber.com).

## Grace period

Past-due subscriptions enter a **grace period** (default 7 days)
before the API hard-blocks. Grace gives you a window to fix the
payment method without disrupting traffic; Agnes returns
[`billing_grace_period`](/errors/billing_grace_period) and continues
serving requests. After grace expires, the API returns
[`billing_required`](/errors/billing_required) and stops serving
analyzer endpoints.

The relevant headers on every response during a problem state:

* `X-Subscription-Status` — `active` / `past_due_grace` / `past_due`
  / `canceled`.
* `X-Billing-Status` — `active` / `grace` / `blocked` / `sandbox`.
* `X-Grace-Days-Remaining` — countdown when in grace.

## Notifications

Agnes sends transactional billing email via SendGrid:

* Trial 50% / 80% / 100% used.
* Invoice paid / failed.
* Spending limit alerts (soft and hard).
* Payment method updated.

Recipients are tenant owners and admins. The email templates are
operator-configurable; you do not get to customise them per tenant.

## Cancelling

Cancel from the Customer Portal. The subscription:

1. Continues serving requests until the end of the current billing
   period.
2. Generates a final invoice for any on-demand usage.
3. Downgrades the tenant to **trial** (or to no plan if you ran out
   of trial tokens) at period end.

Cancelling does **not** delete your tenant. To delete the tenant
entirely, see [Organizations](/administration/organizations).

## Sandbox stays free

`ak_test_*` traffic bypasses billing entirely:

* `BillingEnforcementService.check_billing_access` short-circuits with
  `status="sandbox"` for sandbox keys.
* `X-Agnes-Billing-Status: sandbox` is on every response so dashboards
  can exclude sandbox.
* Sandbox traffic does not consume your token bucket.

See [Sandbox mode](/testing/sandbox-mode).

## Next

* [Errors → `billing_required`](/errors/billing_required)
* [Errors → `billing_grace_period`](/errors/billing_grace_period)
* [Rate limits](/api-reference/rate-limits)