Categories & Event Map
When a cashier opens the financial modal for a job, BayWise Payments does not present every possible financial event and ask them to pick. It presents the events that make sense for that specific entity, at that specific stage, given that entity’s conditions. A job in the “Invoiced” stage with an insurance flag gets different prompts than a walk-in oil change being closed out with cash. A business expense recorded from the Business Tab gets a different category set than a customer-facing transaction.
The system that makes these decisions is the event map — a configuration table that maps combinations of entity type, lifecycle stage, and metadata conditions to the financial events that should be offered.
What the event map is
The event map is a table of 146 rows (at system default). Each row is a rule that says: “When the entity is of this type, at this stage, under these conditions, offer these financial event categories with these payment methods.”
A simplified example of what three rows might express:
| Entity type | Stage | Condition | Events offered |
|---|---|---|---|
| Job | Invoiced | is_insurance = true | Insurance claim receipt, Customer excess collection, Sublet cost |
| Job | Completed | is_insurance = false | Customer payment, Parts cost, Labour allocation |
| — | — | — | Rent, Salaries, Utilities (business-level events) |
The event map is what allows BayWise Payments to behave differently for different business types without requiring code changes. A workshop, a parts distributor, and an authorised dealer each operate in the same system but see different financial prompts because their event maps are configured differently.
Conditions
Each event map row can specify conditions that must be true for the row to apply. Conditions are evaluated against the entity’s metadata at the time the financial modal is opened.
The available conditions are:
- is_insurance — whether the job involves an insurance claim
- has_sublet — whether the job includes outsourced/sublet work
- job_type — the type of job (service, body, paint, mechanical, electrical)
- location — the location where the entity exists
- customer_type — the classification of the customer (retail, fleet, trade, insurer)
Conditions can be combined. A row might specify is_insurance = true AND has_sublet = true to offer sublet cost recovery events only on insurance jobs that actually include sublet work. Conditions that are left blank on a row are treated as wildcards — the row applies regardless of that condition’s value.
Business category groups
The event map organises financial events into 13 business category groups. These groups are not arbitrary labels — they reflect the operational structure of automotive service businesses and adjacent industries.
| Group | Covers |
|---|---|
| Compensation | Salaries, wages, commissions, bonuses, overtime |
| Operating Expenses | Parts, consumables, tools, equipment purchases |
| Recurring OpEx | Rent, utilities, insurance premiums, subscriptions |
| Statutory | Tax payments, regulatory fees, licensing costs |
| Marketing | Advertising, promotions, sponsorships, loyalty programs |
| Financing | Loan repayments, interest, lease payments, credit facility fees |
| Software | SaaS subscriptions, diagnostic tool licenses, DMS fees |
| Franchise | Franchise fees, brand royalties, marketing levies, training charges |
| Inter-branch | Transfers between locations in the same organisation |
| Marketplace | Parts marketplace purchases, online platform fees |
| OEM/Dealer | Warranty claims, dealer holdbacks, OEM program payments |
| Franchisor | Revenue from franchise locations (for franchisor entities) |
| Sales Revenue | Customer payments, service revenue, parts sales |
At Tanaka Auto Service in Osaka, which operates as an independent workshop, the Franchise, OEM/Dealer, and Franchisor groups are largely unused. At Al Futtaim Auto in Dubai, which operates as an authorised dealer network, the OEM/Dealer and Inter-branch groups are active daily. The same system, different configurations.
Scope override resolution
Event map rows exist at three levels. When multiple rows match the same entity-type/stage/condition combination, the most specific scope wins:
- Location-specific — a row configured for a particular location overrides everything else
- Org-specific — a row configured at the organisation level applies to all locations that do not have a location-specific override
- System default — the built-in rows that ship with BayWise Payments apply when neither location nor org overrides exist
This three-tier resolution means that Santos Body Works in Sao Paulo can customise the events offered for insurance jobs at their flagship location while keeping the organisation defaults for all other locations. The resolution is deterministic and predictable — there is no ambiguity about which row applies.
Scope overrides are resolved server-side. The client never sees the full override chain — it receives only the final resolved set of events for the current entity, stage, and conditions.
Entity-level event resolution
When the financial modal opens for a specific entity (a job, an invoice, a purchase order), the system resolves the applicable events by handling scope override resolution and metadata condition matching on the server side.
The system receives the entity type, current lifecycle stage, and the entity’s metadata (insurance flag, sublet flag, job type, customer type). It evaluates every matching event map row, applies scope override resolution, and returns the resolved list of events with their categories and suggested payment methods.
This server-side resolution ensures that the cashier at Sharma Motors in Mumbai sees exactly the right events for the entity in front of them, without the client needing to understand the override logic or hold the full event map in memory.
Business-level event resolution
For transactions that are not tied to a specific entity — rent payments, salary disbursements, utility bills recorded from the Business Tab — the resolution is simpler. The system queries event map rows where both entity type and lifecycle stage are not linked to a specific entity, which identifies business-level events. Scope override resolution still applies (location-specific overrides org-specific overrides system default), but there is no metadata condition matching because there is no entity to inspect.
The client applies this scope override for business-level events, since the filtering is straightforward and avoids an additional server call for a common operation.
Caching behaviour
Events are cached per modal session. When the financial modal opens for an entity, the resolved event set is fetched once and held for the duration of that modal interaction. If the cashier closes the modal and reopens it, a fresh resolution is performed.
A force-refresh is triggered automatically when the entity’s lifecycle stage changes or when entity metadata is modified (for example, toggling the insurance flag on a job). These changes could alter which event map rows match, so the cached set is invalidated and re-fetched.
If you update the event map configuration in settings, those changes take effect for the next modal open. You do not need to refresh the page or restart the application — the per-session caching means each new modal interaction picks up the latest configuration.
Why this matters
The event map is the mechanism that makes BayWise Payments adaptable. Without it, every workshop would see the same financial prompts regardless of their business type, operational model, or jurisdictional requirements. With it, the system adapts to the business rather than requiring the business to adapt to the system.
A tyre shop, a body repair specialist, a full-service dealer group, and a mobile mechanic franchise all record financial transactions. But the transactions they record, the categories they use, and the payment methods they offer differ substantially. The event map captures these differences as configuration rather than code, which means the system can be tailored during setup rather than during development.
At Muller Werkstatt in Berlin, the event map was configured during onboarding to reflect German statutory requirements for invoice categorisation. No code was changed. The same system that serves workshops in Mumbai, Dubai, and Sao Paulo serves Berlin with locally appropriate financial event prompts.
Related pages
- Entities & Transactions — the entity lifecycle stages that the event map keys off
- The Financial Modal — the interface where resolved events are presented to the cashier
- Recurring Obligations — recurring events use the same category system
- Payment Methods — the methods suggested alongside each event category