> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/metering-and-billing/billing.md).

# Metering and billing overview

Kangal exposes two related but separate commercial controls:

* **Entitlements and quotas** decide whether a tenant can use a feature and how much capacity is available.
* **Metering and billing** measures gateway usage, calculates a USD invoice preview, and can persist exact billing periods.

Assigning a tenant entitlement plan does not automatically rewrite every gateway's `plan_code`. Verify both views when onboarding or changing a contract. See [Entitlements and metering](/metering-and-billing/entitlements-metering.md) for the enforcement and data-quality details.

## Console workflows

### Entitlements

Open `/<locale>/dashboard/admin/entitlements`.

* Tenant admins can inspect their effective plan, enabled features, used and reserved units, limits, periods, warnings, and overrides.
* Super-admins can select another tenant and assign a catalog plan.
* Override, reset, and assignment history are available through the API and audit trail.

### Metering and Billing

Open `/<locale>/dashboard/admin/metering-billing`.

1. Select all gateways or one gateway.
2. Choose a 7, 30, or 90-day preview window.
3. Review requests, overage, AI tokens and provider cost, and active or pending portal applications.
4. Check each row's usage source and quota status.
5. Export the preview as CSV or JSON, or use a persisted ledger/period ID for a final export.

The page also shows whether billing-period close is allowed, the monthly close count or quota, and the latest persisted reconciliation.

## Billing plan catalog

The server-side metering catalog recognizes these gateway plan codes:

| Plan code             | Base per gateway-month | Included requests per month | Overage per 1,000 requests |
| --------------------- | ---------------------: | --------------------------: | -------------------------: |
| `serverless_starter`  |                     $0 |                   1,000,000 |                      $0.20 |
| `serverless_team`     |                    $49 |                   5,000,000 |                      $0.16 |
| `dedicated_cloud`     |                   $499 |                  10,000,000 |                      $0.12 |
| `self_managed_hybrid` |                   $999 |                  25,000,000 |                      $0.05 |

All catalog entries use metered overage rather than a hard request block. Base fees and included requests are prorated by `days / 30` for the selected period. AI provider cost is added when evidence is available; the plan markup is 0%. Invoice previews use USD and set tax to zero.

Missing or unrecognized gateway `plan_code` values fall back to `serverless_starter` in the metering calculation. Confirm the code after gateway creation or update and before closing a billing period.

These values are the runtime catalog, not a substitute for an order form, tax calculation, provider bill, or negotiated contract.

## What is metered

| Meter               | Source and behavior                                                              |
| ------------------- | -------------------------------------------------------------------------------- |
| Requests            | Counts tenant- and gateway-scoped traffic log records in an explicit period.     |
| AI tokens and cost  | Uses successful AI audit events; cache hits and failed requests count as zero.   |
| Portal applications | Reports active and pending applications; these are informational invoice totals. |
| Base fee            | Gateway plan base amount prorated to the selected period.                        |
| Request overage     | Requests above the prorated included amount.                                     |

For an open-ended dashboard preview, seven-day aggregate gateway metrics can be scaled to the selected window when exact records are absent. That result is estimated and cannot be finalized.

## Tenant and gateway scope

Every summary, snapshot, closed period, and export is tenant-scoped. A regular admin cannot substitute another `tenant_id`. An optional `gateway_id` narrows the calculation, and ledger or period lookup still requires the same tenant. Unknown cross-tenant IDs are rejected or appear as not found.

## Operational notes

* Confirm each gateway's recognized `plan_code` before using an invoice preview for a commercial decision.
* Use explicit UTC period bounds and require `data_quality: exact` for an accounting handoff.
* Treat dashboard previews as operational estimates until a ledger snapshot or billing period has been finalized and exported from persisted content.
* Reconcile tenant entitlements and gateway billing plans after every contract change; they are separate controls.

## Preview API

```bash
export KANGAL_URL='https://api.example.com'
export KANGAL_API_TOKEN='<tenant-admin-token>'

curl --get "$KANGAL_URL/admin/metering-billing/summary" \
  --header "Authorization: Bearer $KANGAL_API_TOKEN" \
  --data-urlencode 'tenant_id=acme' \
  --data-urlencode 'days=30'
```

Use both `period_start` and `period_end` for an exact bounded calculation. The end boundary is exclusive, and a period cannot exceed 366 days.

Preview exports are convenient but can contain estimates. For accounting handoff, export a finalized ledger snapshot or closed period:

```bash
curl --get "$KANGAL_URL/admin/metering-billing/invoice/export" \
  --header "Authorization: Bearer $KANGAL_API_TOKEN" \
  --data-urlencode 'tenant_id=acme' \
  --data-urlencode 'period_id=<closed-period-id>' \
  --data-urlencode 'format=csv'
```

`ledger_id` and `period_id` cannot be supplied together. A draft ledger must be finalized before export.

## Billing status meanings

| Status              | Meaning                                                                     |
| ------------------- | --------------------------------------------------------------------------- |
| `current_cycle`     | The selected period has exact, billing-eligible data.                       |
| `estimated_preview` | At least one gateway relies on scaled metrics or estimated AI cost.         |
| `usage_unavailable` | Required usage evidence cannot be proven.                                   |
| `within_limit`      | Less than 80% of included requests is used.                                 |
| `approaching_limit` | At least 80% is used but the included amount is not exceeded.               |
| `overage`           | Included requests are exceeded under metered-overage policy.                |
| `blocked`           | Reserved for a hard-limit billing policy; none of the catalog plans use it. |

## Troubleshooting

| Symptom                           | Check                                                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| No usage appears                  | Confirm the gateway belongs to the tenant and emits traffic logs or aggregate metrics.                             |
| Summary returns `503`             | A metering source failed; Kangal fails instead of silently reporting zero.                                         |
| Preview is estimated              | Use explicit period bounds and ensure exact traffic and billed AI audit data exist.                                |
| Usage is unavailable              | AI aggregates indicate usage but exact successful event evidence is missing or incomplete.                         |
| Expected plan is shown as Starter | The gateway `plan_code` is missing or not in the recognized billing catalog.                                       |
| Export returns `409`              | The ledger is still draft, data is estimated/ineligible, the watermark mismatches, or integrity validation failed. |
| Period close is denied            | Check tenant billing enablement, period-close enablement, and monthly close quota.                                 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/metering-and-billing/billing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.