How the token economy works

Tokens, credits, and where the balance lives

A token is a unit of bookable value. When a member books a meeting room, the booking has a token cost, and that cost is subtracted from a balance. LiteHQ uses the words tokens and credits interchangeably in the UI; they are the same thing.

There are two balances that matter, and they describe the same pool from two angles. The company pool is the canonical balance: every tenant company has one shared pool, and that is the number bookings actually spend against. The per-member balance is a view of how the pool is split across that company's active members, so a tenant admin can see who has what. When the two ever disagree, the company pool is the source of truth.

Every change to the balance is written to a transaction ledger: monthly refreshes, booking usage, refunds, and manual adjustments all leave a dated row. That ledger is what powers the wallet history and the operator token reports, so the running balance can always be reconstructed from it.

• Company pool: the shared, canonical balance a tenant company spends from.
• Per-member balance: a per-person split of the same pool, shown to tenant admins and members.
• Transaction ledger: a dated audit row for every refresh, booking, refund, and adjustment.

How allowances are granted per plan

Allowances flow from membership plans, not from a single number you type on the company. Each member of a tenant company sits on a rate plan, and that plan carries a monthly token amount. A company's total monthly allowance is the sum of the token amounts of all of its active members.

The token amount for a member is resolved in a specific order, so you always know which value wins. If there is a per-facility override on the member's plan (a facility-and-plan specific token amount), that override is used. Otherwise the plan's own default token amount is used. If neither is set, that member contributes zero tokens.

This means a company with three active members on a plan worth 100 tokens each has a 300-token monthly allowance. Companies whose members all resolve to zero tokens (for example parking-only or storage-only arrangements) simply have no allowance, and the monthly refresh leaves them untouched.

• Per-member token amount = per-facility plan override, else the plan default, else zero.
• Company monthly allowance = the sum of those token amounts across all active members.
• Only active memberships count toward the allowance; a company with no token-bearing plans has no allowance.

The monthly refresh: what happens on the 1st

Balances reset to the plan allowance on the 1st of each month. The reset is evaluated against the workspace time zone, which is Pacific/Auckland by default, so it lands at the start of the 1st in your local time rather than at an arbitrary UTC hour.

The refresh runs as a daily background job and is safe to run more than once: it only acts once per calendar month per company, and a missed day self-heals on the next run. That design exists precisely so a single failed run never leaves members short.

The reset is not a naive overwrite. The target balance is the plan allowance plus this month's net activity so far. On the 1st at midnight that net is effectively zero, so members start the month with their full allowance. If the job ever has to reconstruct a balance mid-month, it rebuilds the correct as-if-refreshed-on-the-1st figure without handing back tokens that were already spent this month. At the same time, each active member's per-member balance is reset to its own allowance, so the per-person view stays consistent with the company pool.

• Resets happen on the 1st, evaluated in the workspace time zone (Auckland by default).
• Runs daily and only acts once per company per month; a missed run catches up the next day.
• Resets the company pool to allowance plus this month's net activity, and each active member's balance to its own allowance.

How bookings deduct and refund tokens

When a booking is created, its token cost is calculated from the resource's rate, the duration, and whether the time falls in or out of business hours (out-of-hours time can be priced differently). Member-specific rates are applied first where they exist. The resulting cost is then deducted from the balance.

The deduction is atomic with the booking itself. The booking row and the token debit are written in a single transaction that locks the balance first, so two people booking the last of a shared pool at the same instant cannot both succeed against the same tokens. The same booking is also safe to retry: a repeat with the same key returns the original booking instead of charging twice. Deductions come out of the company pool when the booking belongs to a company; for an individual member without a company pool, they come out of that member's balance.

Cancelling a booking refunds tokens back to the same balance, subject to the cancellation policy attached to the resource (or the workspace default policy). A policy can apply a percentage fee based on how much notice was given, so a late cancellation may refund less than the original cost. The cancellation email shows both the refund amount and any fee applied.

• Booking cost depends on the rate, duration, business-hours vs out-of-hours pricing, and member rates.
• Deduction and booking creation happen together atomically, with a lock so a shared pool cannot be double-spent.
• Cancellations refund to the same balance, minus any cancellation-policy fee tied to the notice given.

Overage: letting balances go below zero

By default a booking is rejected if the balance cannot cover its cost: the member sees an insufficient-tokens message and the booking is not created. That keeps a company from spending tokens it does not have.

If you want bookings to go through even when the pool is empty, you can allow overage. With overage enabled, a booking is permitted to push the balance negative, and the shortfall is tracked rather than blocked. This is the mechanism behind a company showing as in overage on the operator token report: a negative balance with overage explicitly enabled.

Overage can be set as a per-company setting, with a workspace-wide default that applies when a company has not been set individually. Use it where you would rather bill the overage afterward than have a member blocked at the point of booking.

• Default: bookings that exceed the balance are rejected with an insufficient-tokens error.
• Overage on: bookings are allowed to push the balance negative and the shortfall is tracked.
• Set overage per company, or set a workspace-wide default for companies you have not configured individually.

Configuring allowances and tokens as an operator

Because allowances come from plans, the place you set them is the rate plan and its per-facility overrides, not a free-text box on the company. Set the token amount on a plan to grant every member on that plan that many tokens per month; add a per-facility override on the plan when a particular resource should grant a different amount.

On a tenant company's detail screen you can see the resulting picture: each active member's plan, that plan's token allowance, the company's total monthly allowance, and the current available balance. This is the screen to check when an operator asks why a company's tokens look high or low: it shows exactly which plans are contributing.

Workspace-level token settings (the token value, currency, and the overage default) live in your organization settings. The token value is what converts a money rate into a token cost, so changing it changes how many tokens future bookings cost. As a tenant admin you generally consume the allowances an operator has configured rather than setting them yourself; member balances and history are visible in the wallet.

• Grant allowances by setting the token amount on a rate plan, with per-facility overrides where needed.
• Review a company's contributing plans, total monthly allowance, and live balance on its detail screen.
• Set token value, currency, and the overage default in organization settings.

Troubleshooting and reconciliation

If tokens did not refill on the 1st, first confirm the company actually has an allowance: a company whose members all resolve to zero tokens is intentionally skipped. Because the refresh runs daily and self-heals, a balance that is briefly wrong on the 1st itself often corrects within a day.

If a balance looks wrong, reconcile it against the transaction ledger. Every refresh, booking, refund, and adjustment is a dated row, and the running balance is the sum of those rows. The wallet shows refreshes as a monthly refill entry, bookings as usage, and cancellations as refunds, which makes it straightforward to trace where a number came from.

If a member sees a zero balance and an empty history together, treat it as possibly a failed load rather than genuinely no tokens: the wallet flags this case so you do not mistake a degraded read for an empty pool. Re-check after a refresh of the page before assuming the balance is actually zero.

• No refill on the 1st: confirm the company has a non-zero allowance, then allow a day for the self-heal.
• Balance looks wrong: reconcile against the ledger, where refresh, usage, and refund rows sum to the balance.
• Zero balance plus empty history can indicate a failed load, not a truly empty pool; reload before concluding.

Frequently asked