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

# Billing and Credits

> Production plans, workspace credits, server-owned Checkout SKUs, metering, and payment safety.

Esheria uses workspace credits across API, CLI, and MCP traffic. Credits are a
workload/value unit—not LLM tokens—and the same plan, pack, feature, rate, and
balance controls apply on every surface.

## Production Plans

| Plan                  |         Price |        Included credits | Pack access                                                    | Requests/minute |
| --------------------- | ------------: | ----------------------: | -------------------------------------------------------------- | --------------: |
| Sandbox               |           \$0 | 500 once, valid 14 days | Choose 2 published packs                                       |              30 |
| Developer             |    \$99/month |            10,000/month | Choose 5 published packs                                       |              60 |
| Team                  |   \$449/month |            50,000/month | Choose 20 published packs; monitoring reads and graph coverage |             180 |
| Business              | \$1,499/month |           250,000/month | All published standard packs                                   |             600 |
| Enterprise / Embedded | \$3,500/month |           500,000/month | Standard plus contracted custom/premium packs                  |           1,200 |

Enterprise plans include contracted support, throughput, SLA, and data-rights terms. Taxes, premium/custom content, and negotiated services may be additional.

<Info>
  Existing balances are grandfathered. Esheria does not remove or
  retroactively debit credits when publishing a new catalog or pricing rule.
</Info>

## Top-up SKUs

| SKU                    | Available to                                   | Price | Credits | Expiry   |
| ---------------------- | ---------------------------------------------- | ----: | ------: | -------- |
| `business-topup-50000` | Business, Enterprise / Embedded, Grandfathered | \$500 |  50,000 | 365 days |
| `developer-topup-1000` | Developer                                      |  \$15 |   1,000 | 365 days |
| `team-topup-10000`     | Team                                           | \$120 |  10,000 | 365 days |

Use `esheria billing plans` or `GET /api/v1/billing/plans` as the source of
truth. The response includes exact prices, available SKUs, workspace plan and
pack policy, and the active pricing-rule catalog.

## Checkout

Checkout accepts one server-owned SKU. You cannot submit the price, credits,
quantity, grant expiry, plan, or entitlement.

```bash theme={null}
esheria billing plans
esheria billing checkout --sku-id developer-topup-1000
```

```bash theme={null}
curl --compressed -sS -X POST \
  "https://api.esheria.ai/api/v1/billing/topups/checkout-session" \
  -H "content-type: application/json" \
  -H "x-api-key: $ESHERIA_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"sku_id":"developer-topup-1000"}' | jq
```

The API creates an internal order before redirecting to Stripe. Payment
webhooks validate the Stripe Price and line item against that order. Credit
grants never come from browser, CLI, or Checkout metadata values.

## Metering

Production pricing version: `2026-07-14-v2`.

| Operation                     |               Credits | Availability                     |
| ----------------------------- | --------------------: | -------------------------------- |
| Claim verification            |                    15 | Entitled plans                   |
| Customer impact read          |     2 + 1/100 impacts | Business+                        |
| Customer impact recompute     |    50 + 1/100 impacts | Business+ and `customer:write`   |
| Customer profile read         |     2 + 1/100 results | Business+                        |
| Customer profile write        |                    10 | Business+ and `customer:write`   |
| Customer state patch          |                     5 | Business+ and `customer:write`   |
| Execute source check          |         50 + 5/source | Business+ and `monitoring:write` |
| Fact listings                 |     2 + 1/100 results | Entitled plans                   |
| Full pack export              |          250 + 10/MiB | Business+                        |
| Graph coverage                |                     2 | Team+                            |
| Graph projection rebuild      |   100 + 1/1,000 facts | Business+ and `graph:write`      |
| Graph query/entity profile    |     8 + 1/100 results | Entitled plans                   |
| Monitoring read/currentness   |     2 + 1/100 results | Team+                            |
| Pack discovery/detail         |                     1 | Entitled plans                   |
| Persisted applicability       | 25 + 1/50 obligations | Business+ and `customer:write`   |
| Source-watch write            |                    10 | Business+ and `monitoring:write` |
| Stateless applicability       |     10 + 1/50 results | Entitled plans                   |
| Versions, diff, change events |     2 + 1/100 results | Entitled plans                   |

The API reserves credits before work starts, charges successful work once, and
releases failed requests. Usage rows retain every referenced pack, the pricing
rule/version, request and response units, final charge, and `trace_id`.
An in-process reconciler releases stale reservations and safely reclaims due
or interrupted Stripe events.

```bash theme={null}
esheria billing balance
esheria billing usage --limit 25 --format json
```

## Entitlements And Replays

* Workspace settings choose the packs available under the plan.
* A token inherits those packs by default or narrows to a subset.
* Every pack in a multi-pack graph/customer request is checked.
* Full export and hosted operator workflows also require plan features.
* Authentication and current authorization run before an idempotent response
  can be replayed. Replay records are isolated by workspace and token.

## Renewals, Refunds, And Disputes

Recurring invoice credits are derived from Stripe Price-to-plan mappings and
granted once per paid invoice, including concurrent duplicate deliveries.
Failed and stale-processing Stripe events remain retryable. Self-service
Checkout refuses a second current subscription for the same workspace.

Refunds reverse the proportional credits tied to the refunded payment.
Disputes temporarily reverse the affected value. If those credits were already
used, Esheria records credit debt instead of directly consuming an unrelated
grant. A won dispute clears that debt first and restores any remaining credits.

## Errors

| HTTP | Code                                                  | Meaning                                                             |
| ---: | ----------------------------------------------------- | ------------------------------------------------------------------- |
|  401 | `unauthorized`                                        | Token is missing, invalid, revoked, or expired                      |
|  402 | `credits_exhausted`                                   | No usable credits remain                                            |
|  403 | `forbidden` / `feature_not_entitled`                  | Scope, pack, or plan feature is missing                             |
|  409 | `idempotency_key_conflict`                            | Key was reused with a different payload in the same principal scope |
|  429 | `rate_limited`                                        | Pre-auth abuse limit or plan request limit was exceeded             |
|  503 | `billing_unavailable` / `billing_pricing_unavailable` | Ledger or pricing catalog failed closed                             |

MCP intentionally does not expose billing mutation, Checkout, or token
management tools. Configure billing and tokens in the Dashboard or CLI first.