Referrals & Commissions

How referrals work

A referral in Belvak is a partner who introduces clients to your business. Partners can be individuals, agencies, freelancer networks, former clients, or any other source of new business. Each partner carries their own commission terms, and qualifying payments from clients they introduced generate commission entries based on those terms.

Two modules work together

The referrals system spans two sidebar modules:

• Referrals - the partner directory. Stores names, contact info, and commission terms. This is where you add and edit partners.
• Commissions - the per-payment commission ledger. The sidebar label is "Commissions" but the page title at the top reads "Referral Commissions". Each row represents a single commission, generated automatically by a source payment or added manually.

Why use referrals

• Measure which acquisition channels actually drive revenue.
• Calculate commission earnings automatically as client payments come in, instead of running a spreadsheet on the side.
• Pay partners from the Commissions page, with each commission stored in its payment currency.
• Audit who introduced every client in your workspace.

Permissions

Partner data and commission data are governed by two independent permission resources, so you can give finance staff view-only access to commissions without exposing the partner directory, or vice versa:

• Referrals - controls who can view, add, edit, or delete partner records.
• Referral Commissions - controls who can view, add, edit, or delete commission rows (including marking paid, reverting, and bulk delete).

See roles and permissions for the full matrix.

Adding and editing a referral partner

Partners are created through a two-step form. Step 1 captures contact info; Step 2 sets the commission terms that drive how much this partner earns on each client payment.

Adding a partner

1. Open the Referrals page from the sidebar.
2. Click Add in the top-right of the table.
3. Step 1 - Contact Info: fill in the partner's name, phone number, and email.
4. Step 2 - Commission Terms: choose the commission type, rate, duration, cap, and whether maintenance payments count. See commission rules for the field-by-field reference.
5. Click Submit to create the record.

Contact info field reference

• Referral Name - required. Up to 100 characters.
• Phone Number - optional. Up to 15 characters. The form does not enforce a specific phone format; enter whatever your records show.
• Email - optional. Up to 100 characters. Standard email validation applies when provided.

Editing a partner

Open the partner from the table to view the drawer, then click Edit. The same two-step form opens. The three-dot menu on the row and the right-click context menu both offer an Edit shortcut as well.

Deleting a partner

Deletion is blocked when a partner has referred clients or commission records. Belvak responds with a count of blocking records, for example "3 referred clients, 12 commission records", and asks you to reassign or remove them first. This is intentional: deleting a partner with history would orphan revenue attributions and break the audit trail.

Linking clients to a partner

Partner records on their own do not generate commissions. You also need to link clients to them. See linking clients to a referral for the workflow.

Linking clients to a referral

Every client in Belvak must have a referral source. This is enforced at the client form level: the Who Introduced you to the Client? field is required.

On the client form

When you add or edit a client (see adding and managing clients), the Who Introduced you to the Client? dropdown lets you pick from your existing partner records. Without this, you cannot save the client.

What if the client came in directly

Because the field is required, create one permanent in-house referral record (e.g. "House" or "Direct") and assign it to every client who arrived without a partner.

Quick-link from the Referrals table

From any partner row, the Add Client action (in the three-dot menu or right-click) opens the client form with that partner already selected. The drawer also exposes the same action as a primary button. Use this when you are creating a client from a known partner.

Viewing the clients of a partner

• View Clients row action - jumps to the Clients page filtered to that partner.
• Client Impact treemap - in the drawer's Overview tab, up to eight tiles sized by revenue, coloured by activity (active, completed, idle). Clicking a tile opens that client.

One referral source per client

A client can only be associated with one partner at a time. If a client was introduced by two parties and you want to share commission, that is not natively supported: pick the primary partner and arrange the split outside Belvak. To transfer a client from one partner to another, edit the client and change the source. Existing commissions stay with their original partner (see how commissions are generated).

Commission rules: type, duration, cap, maintenance

Step 2 controls commission type, duration, cap, and maintenance inclusion. Changes to these settings do not reprice existing commission rows, so corrections require manual reconciliation.

Commission Type: Percentage vs Flat Fee

• Percentage - the partner earns a share (0 to 100%) of every payment Belvak receives from a referred client. Calculated automatically when each payment is recorded.
• Flat Fee - the partner earns a fixed amount once per engagement. An engagement is a single project or a single maintenance contract. With Unlimited or time-based duration, a flat fee can fire again every time a new project or maintenance contract starts for the same client. To collapse a flat fee to "once per client", set duration to First Engagement Only.

Duration per Client

Duration controls how long after a client is introduced the partner keeps earning commissions on that client's payments.

• First Engagement Only - the partner earns on payments from the first engagement to trigger a commission only. Order of arrival, not order of creation: if Project A is created first but Project B records a payment first, B is the winning engagement and Project A earns nothing.
• 6 / 12 / 24 Months - the partner earns on payments recorded within the time window, counted from the client's creation date (not the partner's join date). Payments after the window earn nothing.
• Unlimited - no expiry. The partner keeps earning on every qualifying payment forever.

Max Commission per Client (the cap)

Max Commission per Client sets a ceiling on how much one partner can earn from a single referred client. Each client has its own cap; partners are not limited across their whole client list.

• The cap is measured in the partner's commission currency (see commission currency).
• Commissions saved in a different currency are converted to the partner's commission currency at save time. The conversion is preserved on the row, so existing cap usage does not move later when exchange rates change.
• Commission accrues as each payment from that client lands. Once the cap is reached, no further commission is earned from that client, regardless of duration or future payments.
• Manual commission entries count toward the cap. Off-platform payouts you record manually consume the cap budget for that client just like auto-generated rows.
• Leave the field empty for no limit.

Include Maintenance Payments

When enabled, this partner earns commission on maintenance contract payments from each referred client, not just project payments. When disabled, maintenance payments never create commission rows for this partner.

Worked example

What happens when you edit the rules

Editing a partner's commission terms does not automatically reprice any existing commission rows, pending or paid. The new terms only affect commissions generated for source payments recorded after the update.

There is one exception worth knowing: if a source payment is edited while its auto commission is still pending, that pending row is deleted and regenerated against the current referral terms. Once a commission has been marked paid, it is preserved regardless of later term changes. More detail in how commissions are generated.

How commissions are generated

Commissions reach the ledger in one of two ways: auto-generated from project or maintenance payments, or added manually for off-platform deals and adjustments. Both appear in the commission ledger and can be marked paid, reverted, or deleted according to permissions, though manual rows differ from auto rows in two ways noted below.

Auto-generation

When a project payment, or an eligible maintenance payment, is recorded for a client linked to a partner, Belvak attempts to generate a commission row. A row is inserted only when the partner's type, duration, cap, and maintenance rules allow it. Resolution differs by source:

• Project payments: payment -> invoice -> project -> client -> referral
• Maintenance payments: maintenance payment -> maintenance contract -> project -> client -> referral

Percentage auto-commissions use the source payment's currency, while flat-fee auto-commissions use the partner's commission currency. Each auto-row applies the rules described in commission rules. Each row carries a Source pill identifying where it came from. The pill text depends on which surface you are looking at:

• On the standalone Referral Commissions page, the pill reads Project, Maintenance, or Manual.
• In the partner drawer's Earnings tab, the same row reads Project payment, Maintenance payment, or Manual entry.

Manual entries

Use a manual entry when you want to record a commission that did not flow through a Belvak payment. Typical use cases:

• Off-platform payouts (cash, side agreement, legacy deal).
• Retrospective positive corrections (carry-over balance).
• One-off bonuses or recognition payments.

To add one, open the Commissions page from the sidebar and click Add, or open a partner's Earnings tab and use the add action there. Important constraints:

• Positive amounts only. The form requires Commission Amount greater than zero. Refunds or negative adjustments are not supported through manual entry; settle those off-platform.
• You need the referralpayments.can_add permission.
• Manual rows count toward the partner's per-client cap (see Max Commission per Client).
• If a manual commission pushes the partner over the per-client cap, Belvak saves the row but surfaces a yellow warning notification. Future automatic commissions for that client may stop entirely or be reduced to the remaining cap budget.
• Manual rows do not satisfy the flat-fee once-per-engagement check, so a manual entry will not silence a later auto-generated flat-fee row for the same engagement.

When a source payment is edited

• Pending auto rows for that payment are recomputed: the existing pending row is deleted and a new one is inserted reflecting the updated amount and current partner terms.
• Paid rows are preserved. Belvak uses carryover logic so historical accounting is not retroactively rewritten.
• If the edited amount is smaller than what has already been paid out, the partner is now overpaid on that source payment. The Add / Edit drawer surfaces an overpaid commission warning so the bookkeeper can decide how to settle it (issue a refund, credit a later payout, or accept the variance).

When a source payment is deleted

• Pending auto rows for that payment are deleted and audit-logged with a reason of parent_payment_deleted. The deletion event shows up as a standard delete entry in the partner's Activity tab.
• Paid rows are left untouched. Belvak does not retroactively edit paid history, and it does not render a "source removed" or "recalculated" badge on affected paid rows. To audit what happened, use the Activity tab on the partner drawer.

To settle pending rows, use Mark paid from the drawer's Earnings tab or the standalone Commissions page.

If Belvak cannot convert between the payment currency and the partner's commission currency at save time, the payment save is blocked with a "currency rate unavailable" message. Try again in a few moments. The issue is transient and resolves on its own.

Paying out commissions

Generated commissions sit in the ledger as Pending until you mark them paid. Two surfaces let you work with the ledger: the partner drawer's Earnings tab (scoped to one partner) and the standalone Referral Commissions page in the sidebar. The drawer is scoped to one partner; the standalone page supports filtering and bulk actions across partners.

What is on a commission row

• Currency (percentage auto-commissions) - the currency of the source payment.
• Currency (flat-fee auto-commissions) - the partner's commission currency.
• Currency (manual rows) - whichever currency you select when adding the entry.
• Triggering amount - the source payment's amount that produced this commission.
• Commission amount - what the partner actually earns.
• Status - Pending or Paid.
• Paid date - set automatically when you mark a row paid.
• Payment method - Cash, Bank Transfer, Check, or Other.
• Notes - free-text context.

Marking commissions paid

Three workflows, depending on scope:

• Per row. Use the row's Mark paid action, available on both surfaces.
• Bulk for one partner. Open the partner drawer's Earnings tab. If anything is pending, the alert banner exposes a Mark all as paid CTA.
• Bulk across partners. On the standalone Referral Commissions page, select rows from any partners and use the bulk Mark as Paid action.

Marking paid records paid_date = today automatically.

Reverting to pending

Revert is available only on the standalone Referral Commissions page, both per row and as a bulk action. The partner drawer's Earnings tab does not expose a revert action on paid rows. Reverting clears the paid date and moves the row back to Pending. Use this for corrections, like a row that was marked paid in error.

Bulk delete

The standalone page also supports bulk delete (selection plus bulk action), gated by referralpayments.can_delete. Use sparingly: deleting paid rows breaks the audit trail of what you have actually settled with the partner.

The standalone Referral Commissions page

• Status filter. The segmented control renders Pending, Paid, then All, and defaults to Pending so the page opens on actionable work.
• Filters. By Referral (dropdown) and by Client (text search).
• Toggle-on columns. Engagement, Triggering Amount, Paid Date, Method, and Currency can be enabled from the column visibility menu.
• Totals row. Aggregated by currency, so a workspace with mixed-currency commissions sees one total per currency rather than a forced single-currency conversion.

Multi-currency in practice

Each row stores its own currency. The drawer's summary cards convert to the workspace default for totals; mixed-currency partners see a small chip next to those figures indicating that the figure is converted. When the conversion rate is unavailable for one of the currencies in the mix, the Overview "Commission earned" card and the Revenue Trend chart show a conversion incomplete chip so you know the displayed total is approximate. The per-client cap follows the partner's commission currency, not the row's currency. When a commission row is recorded in a different currency, Belvak converts it to the partner's commission currency for cap accounting and keeps that conversion fixed on the row.

To set your workspace default, see currency configuration.

Permission summary

• referralpayments.can_view to see commissions.
• referralpayments.can_add to add manual entries.
• referralpayments.can_edit to mark paid or revert.
• referralpayments.can_delete for bulk delete.

View-only finance staff can audit everything without changing anything.

The referral drawer

Clicking any row on the Referrals page opens the partner drawer with four tabs: Overview, Earnings, Activity, and Notes.

Header

The header carries the partner's name, a tier pill (Active partner, New, or Idle), and clickable contact details: phone as a tel: link, email as a mailto: link, joined date, and last referral date.

Overview tab

• Performance cards - Total clients, Revenue generated (with a mixed-currency chip when applicable), Commission earned (paid plus pending breakdown; this card also carries the conversion-incomplete chip when applicable), and Conversion rate ("X of Y converted").
• Revenue Trend chart - with a 6M / 12M / All time selector. Only the All time range is truncated, and only when the partner has more than 48 months of data; 6M and 12M never truncate. The chart has its own conversion-incomplete chip.
• Commission Terms card - a read-only audit of rate, duration, cap, and maintenance inclusion. The cap row is labelled "Cap per client" here, while the form labels the same setting "Max Commission per Client".
• Client Impact treemap - up to eight client tiles sized by revenue, coloured by activity (active, completed, idle). Click a tile to open that client.

Earnings tab

• Pending alert banner with a Mark all as paid CTA when anything is pending.
• Summary cards - Total earned, Paid out (with the last paid date), and Outstanding (count of pending entries). Note: these summary cards do not currently render a conversion-incomplete chip, even when the underlying totals include converted figures.
• 6-month commission accrual stacked bar (paid in indigo, pending in amber).
• Per-row commission ledger. See paying out commissions for the row anatomy and actions.

Activity tab

A paginated timeline of create, update, and delete events on the partner, on the partner's commissions, and on the partner's clients. 20 entries per page, with a Load more button. Deletion events for pending commissions cascaded by a source-payment delete also appear here.

Notes tab

Free-text notes scoped to the partner record. They are not shared with the partner's clients or with individual commission rows.

The Referrals table and Insights bar

The Referrals page has a configurable table with a collapsible insights panel above it. The table uses the common table features described in the dashboard guide.

Default columns

• Name - avatar, partner name, a small tier dot, and a "new" chip when the partner was created in the last 14 days.
• Clients - count of clients linked to this partner.
• Revenue - formatted in the workspace default currency. The mixed-currency chip you see in the drawer does not appear in the table.
• Trend - a six-month sparkline of revenue from this partner's clients.
• Last referral - relative date.
• Comm. - the partner's commission rate. For percentage partners, a mini pill with the percent value. For flat-fee partners, a small orange pill with the flat amount.
• Action - the three-dot row menu.

Toggle-on columns

Use the column visibility button to enable Phone, Email, Date Added, Created At, Updated At, and Total Earned.

Status filter (segmented tabs above the table)

Three values, evaluated in priority order:

• New - takes precedence for partners added in the last 14 days, regardless of client count.
• Dormant - not new, and zero linked clients.
• Active - anyone else.

Tier marker dot

A small coloured dot next to the partner name, derived from the 75th-percentile revenue threshold across revenue-generating partners in the visible table rows. When you filter or search, the percentile is recomputed against the filtered rows. Tiers:

• Top performers - revenue at or above the 75th percentile.
• Active - has clients but below the 75th percentile.
• No clients yet - no linked clients.

Search filters

Open the filter popup from the table header. The available filters are:

• Name, phone, email (text), and Commission (numeric).
• Commission Type (Percentage / Flat Fee), Commission Duration, and Includes Maintenance (yes / no).
• Last Referral bucket: within 30d, 90d, 6mo, 12mo, or Never.
• Has Pending Payouts (yes / no).
• Has Earnings (yes / no).
• Missing Contact Info (email / phone / both).

Row actions

• Add Client - opens the client form with this partner pre-selected as the source.
• View Clients - jumps to the Clients page filtered to this partner.
• View Commissions - jumps to the standalone Referral Commissions page filtered to this partner.

The Insights bar

A toggle in the page header opens or closes the insights panel above the table. The range selector does not affect every tile: most figures recompute when you change the range, but some are current-only.

• Range toggle - three values: 6M, 12M, YTD.
• Referral Revenue (range-scoped) - total revenue from referred clients in the range.
• Revenue Partners (range-scoped) - shown as X / Y, where X is partners whose referred clients paid in the range and Y is all referral partners. A subline notes how many partners have ever referred clients.
• Paying Referred Clients (range-scoped) - a conversion percentage with an X of Y clients subline, where X is clients with at least one payment in the range and Y is all referred clients.
• Pending Payouts - workspace-wide and current, not range-scoped. The "paid this period" subline beneath it is the only range-scoped part of this tile.
• Revenue Trend (range-scoped) - a mini-chart of revenue over the range.
• Partner Health - distribution across the three tiers.
• Top Partners - a leaderboard.
• Revenue Concentration (Top 3 share) (range-scoped) - share of revenue from the top three earning partners in the range. Useful for spotting heavy reliance on a handful of channels.
• Average per Partner - mean revenue across all referral partners, not just active ones. Workspaces with many dormant partners see a lower figure here than the active-partner experience suggests.
• Generated insight - a one-line natural-language observation pulled from the figures above.