User budget model

Every metered tenant has a tier budget. You can add a tenant default for all users who do not have a custom budget, or set an override for one user.

Budget precedence

Toqan chooses the effective budget in this order:

1. Per-user override — the custom amount set for one user.
2. Tenant default — the amount set for users in your tenant.
3. Tier budget — the fallback when neither custom value exists.

Each level replaces the level below it. The values are not added together.

flowchart TD
  Start["Calculate a user's budget"] --> Override{"Per-user override set?"}
  Override -->|Yes| UseOverride["Use the per-user override"]
  Override -->|No| TenantDefault{"Tenant default set?"}
  TenantDefault -->|Yes| UseDefault["Use the tenant default"]
  TenantDefault -->|No| UseTier["Use the tier budget"]
  UseOverride --> Effective["Effective user budget"]
  UseDefault --> Effective
  UseTier --> Effective

Example

Assume the tier budget is $50 and the tenant default is $100:

• A user without an override receives a $100 budget.
• A user with a $150 override receives a $150 budget.

Choose the right endpoint

• Use Get the tenant default user budget to see the effective default, its source, and the tier fallback.
• Use Set the tenant default user budget to change the budget for users without overrides.
• Use Clear the tenant default user budget to return those users to the tier budget.
• Use Set budgets for multiple users to apply one custom budget from up to 500 submitted user IDs. Duplicate IDs count toward the limit and are processed once.
• Use Clear a user's budget override to return one user to the tenant default, or to the tier budget when no tenant default exists.

Changes and existing blocks

After storing a tenant default, Toqan makes a best-effort pass over existing user blocks for that tenant. This pass can remove a block when the user's spending is within the new effective budget. It does not create new blocks, and the API response does not report the result of the pass.

Clearing a tenant default changes the fallback for future budget calculations. It does not immediately re-evaluate existing blocks.

Amounts

Send and receive all user-budget amounts as dollar values. For example, 100 means $100. Decimals are allowed.

Tier budgets, tenant defaults, and per-user overrides define the user's budget.

Budget periods and resets

Toqan counts spending per budget period. At the start of each period, used returns to zero and the full effective budget is available again. Unused budget does not carry into the next period.

The length of the period comes from your tenant's plan. It is daily, weekly, or monthly. All periods are aligned to UTC:

• Daily — resets every day at 00:00 UTC.
• Weekly — resets every Monday at 00:00 UTC.
• Monthly — resets on the first day of each month at 00:00 UTC.

Periods are not aligned to your contract date, your invoice date, or a user's signup date. You cannot set a different reset day for one tenant.

A user who reached their budget becomes active again shortly after the reset. This can take a few minutes, so a request in the first minutes of a new period can still get a rejection.