---
title: "Quota periods"
description: "Read the immutable plan snapshot and granted, reserved, consumed, and available units for one access cycle."
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quota periods

## Outcome

你可以读取一条 WorkspaceAccess 的 QuotaSnapshot，解释每个余额，并区分周期结束、Access 截止和 Key 过期。

## One period, one access cycle

QuotaPeriod 属于一条 WorkspaceAccess，并记录：

- `periodStart` 与 `periodEnd`。
- `grantedUnits`、`reservedUnits` 与 `consumedUnits`。
- 创建时的 WorkspacePlan、QuotaStrategy ID 和倍率快照。
- `SCHEDULED`、`ACTIVE`、`CLOSED` 或 `VOID` 状态。

同一 WorkspaceAccess 最多有一个 ACTIVE Period。历史 Period 不删除；纠错通过追加 Adjustment UsageEvent 完成。

## Read the balance

```text
availableUnits = grantedUnits - consumedUnits - reservedUnits
```

| Balance   | Meaning                                   |
| --------- | ----------------------------------------- |
| Granted   | 本周期授予的总 Units。                    |
| Reserved  | ACTIVE 请求已暂时占用、尚未终结的 Units。 |
| Consumed  | 已结算 Usage 或 Adjustment 消耗的 Units。 |
| Available | 新请求当前可预留的 Units。                |

数据库必须始终保持非负余额，且 `reservedUnits + consumedUnits <= grantedUnits`。

## Snapshot semantics

Period 创建时复制 Plan 与 QuotaStrategy 的有效配置。之后发布新 Strategy、切换 Binding 或变更 Access Plan，都不会改写一个 ACTIVE Period 的倍率；新的配置默认在下一 Period 生效。

## Period creation

Provisioning、显式 Renewal 或 Billing Connector 的幂等周期同步可以创建 QuotaPeriod。Stripe/Creem 只提供外部支付与周期事实；Gateway 不实时调用支付系统，而是读取已经同步到 PostgreSQL 的 Access 与 Period。

## Time boundaries

`periodEnd` 只表示额度周期结束。它不等于 `WorkspaceAccess.accessEndsAt`，也不等于 `ApiKey.expiresAt`。三者都有效且有足够 Available Units 时，新请求才可通过。

## Next steps

- [Key, Access, and Period time](/docs/give-users-access/time-boundaries)
- [Reserve, settle, and release](/docs/control-plans-and-quota/reserve-settle-release)

Source: https://nexus.microvoid.io/docs/control-plans-and-quota/quota-periods/index.mdx