Understanding the Settlement Engine
After a concession stand event is complete, the financial data from that event needs to be turned into actual credits and debits in family accounts and organizational fund ledgers. This process is called settlement, and StandShare uses a configurable engine to handle it.
This page explains what settlement means, how the engine works, and why it is designed the way it is.
What is settlement?
Settlement is the process of taking an event's raw financial data (stand sales totals, tip amounts, worker attendance) and converting it into:
- Credits to each attending worker's family account (their share of the event earnings)
- Debits for organizational fund contributions (General Fund, Board Fund, insurance, etc.)
- Penalties for no-show workers (if applicable)
- Fund transactions that update the organization's fund balances
Until an event is settled, the financial data exists only as inputs. Settlement is the step that makes the numbers real -- it creates the actual transaction records that affect account balances.
The settlement lifecycle
Every event moves through a series of states as it progresses toward settlement:
Upcoming --> Active --> Completed --> Settlement In Progress --> Settled
|
Settlement Failed
(validation errors)
| State | What it means |
|---|---|
| Upcoming | The event is scheduled but has not happened yet |
| Active | The event is currently taking place |
| Completed | The event has occurred and attendance is finalized. Ready for settlement. |
| Settlement In Progress | A coordinator is entering financial data and reviewing calculations. Nothing is committed yet. |
| Settled | All calculations are finalized and transactions have been written to family accounts and fund ledgers. This is the end state. |
| Settlement Failed | Something prevented settlement from completing (missing data, validation errors). The coordinator needs to fix the issue and try again. |
Events can only be settled after they reach the "Completed" state. This ensures that worker attendance has been finalized before financial calculations begin.
Settlement templates
The settlement engine is driven by templates -- named, reusable configurations that define how an event's financials are calculated. A template is an ordered list of line items, where each line item represents one step in the calculation.
Think of a template as a recipe: it defines the ingredients (income sources), the preparation steps (deductions and fees), and the final output (per-worker payout).
Why templates?
Different types of events may have different financial arrangements. An NFL game at a major stadium might have a per-worker fee from the venue plus a percentage of gross sales, while a small college game might pay a simple flat commission. Rather than hard-coding one calculation into the system, templates let the organization define any number of calculation pipelines.
Common templates might include:
- Standard Event -- the default arrangement with all fund deductions active
- Low-Revenue Event -- same calculation but with General Fund and Board Fund deductions turned off
- Concert -- a different venue contract with different rates
- Special Event -- a one-off arrangement with custom line items
What is a line item?
Each line item in a template has:
- A label -- a human-readable name like "Gross Stand Sales" or "General Fund (6%)"
- A category -- whether it is Income, a Fee, a Payout, or a Member Fee
- A calculation method -- how its value is determined
- A destination -- where the money goes (family accounts, a specific fund, or informational only)
The available calculation methods are:
| Method | How it works | Example |
|---|---|---|
| Manual Entry | The coordinator types in the value at settlement time | Gross stand sales, CC tip totals |
| Flat Rate | A fixed dollar amount defined in the template | A $500 venue fee |
| Per-Worker | A rate multiplied by the number of workers | $15 per attended worker |
| Percentage | A percentage of another line item's value | 6% of total commissions |
| Formula | A calculation that references other line items | (Total Income - Total Fees) / Worker Count |
Line items execute in order from top to bottom. Each item can reference the computed result of any item above it. The engine also provides automatic totals like "All Income Total" and "All Fees Total" that any line item can reference.
How settlement execution works
When a coordinator settles an event, the process follows these steps:
1. Template assignment
The event has a settlement template assigned (either the organization's default template or a specific one chosen by an administrator). The coordinator can also override individual line items for this specific event without changing the template itself.
2. Data entry
The coordinator enters values for all manual-entry line items -- typically the gross sales figures and tip totals from each stand. They also confirm worker attendance: which workers showed up and which were no-shows.
3. Live preview
As the coordinator enters data, the engine calculates all downstream values in real time. The coordinator can see exactly what each family will be credited before committing anything. This is a preview only -- no transactions are created yet.
4. Commit
When the coordinator is satisfied with the numbers, they commit the settlement. This is the critical step. In a single atomic database operation, the system:
- Creates a credit transaction for each attending worker's family (their share of the net payout)
- Creates debit transactions for any no-show fees
- Creates fund transactions for each organizational fund that received a deduction
- Updates all affected account and fund balances
- Locks the complete settlement data (all inputs and computed values) as an immutable record on the event
Committing a settlement requires step-up authentication because it is a financial operation. The coordinator will be asked to re-verify their identity before the transactions are created.
5. Notification
After settlement is committed, each affected family receives a notification (email and in-app) with their payout breakdown.
Settlement scope: stand-level vs. event-level
Templates can be configured with one of two scopes:
| Scope | How it works | When to use it |
|---|---|---|
| Stand-level | The engine runs independently for each stand. Each stand has its own sales, tips, and workers, producing its own per-worker payout. | When different stands at the same event perform differently and workers should be paid based on their specific stand's results. |
| Event-level | All stand data is combined first (total sales, total tips, total workers), and the engine runs once on the aggregated numbers. All workers share equally. | When the venue pays a lump sum for the whole event, or when the organization wants equal payouts regardless of which stand a worker was assigned to. |
For example, at a football game with Stand 148 and Stand 149:
- With stand-level scope: Stand 148 might produce $130 per worker while Stand 149 produces $95 per worker, depending on each stand's sales
- With event-level scope: all workers across both stands would receive the same payout calculated from the combined totals
Per-event overrides
Sometimes a single event needs a small adjustment without creating an entirely new template. Per-event overrides allow a coordinator to:
- Disable a specific line item for one event (for example, turn off the Board Fund deduction for a charity event)
- Modify a line item's parameters for one event (for example, change the per-worker rate from $15 to $20 for a special venue)
Overrides apply only to the specific event. The original template remains unchanged and continues to work normally for all other events.
If the same overrides are needed repeatedly for a category of events, it is better to create a new template rather than overriding the same line items each time.
What happens to family accounts
When settlement is committed, each family's account ledger is updated with one or more transactions:
For attended workers: A credit transaction is created for the family, equal to the per-worker payout multiplied by the number of their workers who attended. The transaction record includes the full line-by-line breakdown of how the payout was calculated, so the family can see every income source, every deduction, and the final math.
For no-show workers: A debit transaction may be created, charging the family a no-show fee. This fee is configured in the settlement template and typically equals the lost payout plus any per-worker costs the organization still incurred (such as insurance).
For organizational funds: Fund transaction records are created for each fund that received a deduction (General Fund, Board Fund, etc.), and the fund balances are updated accordingly.
All of these transactions are created in a single atomic operation -- either they all succeed or none of them do. There is no risk of partial settlement.
Can a settlement be reversed?
Yes, but only by an administrator with elevated permissions. If errors are discovered after settlement (for example, incorrect sales figures were entered), an admin can reverse the settlement. Reversal does not delete the original transactions -- instead, it creates offsetting transactions that undo the original amounts. Then the event can be re-settled with corrected data.
This approach preserves a complete audit trail. You can always see what was originally settled, when it was reversed, and what the corrected settlement looks like.
Re-settlement requires step-up authentication and is logged in the audit trail. Affected families are notified of the correction.
Template versioning
When an administrator edits a settlement template, the template's version number is incremented. Events that have already been settled retain a reference to the exact template version they were settled with. This means changing a template never retroactively alters past settlements -- historical data remains accurate even as the organization's financial arrangements evolve.
Key takeaways
- Settlement is the process that turns raw event data into real account transactions
- Templates define the calculation pipeline and can be customized for different event types
- The coordinator enters manual data, previews the results in real time, and then commits
- All transactions are created atomically -- there is no risk of partial settlement
- Families see a full, transparent breakdown of every line item in their transaction record
- Settlements can be reversed and re-done if errors are discovered, with a full audit trail
- Template changes do not affect past settlements
Next Steps
- Getting Started — Set up your account
- How-To Guides — Step-by-step instructions