How to build a commission calculator

What matters here

• A commission calculator is four parts: versioned plan rules, qualifying transactions, a calculation that records its working, and a readable statement.
• Explainability is the requirement, not the feature. Every figure needs a line-by-line derivation a rep can follow without asking.
• Version the plan with effective dates. Recalculating an old period against a new plan is the fastest way to lose trust in the whole system.
• Clawbacks, splits and ramps are where real plans live. A calculator that only handles a flat rate on closed won will not survive its first month.
• Freeze a period once it is paid. Later corrections belong in the next period as an adjustment with a reason, never as a silent rewrite.
• A commission calculator decides what people are paid, so scoped access, managed credentials and a named owner are part of the build.

Who this is for

You run sales compensation, revenue operations or finance. You already know your plans. What you want is a calculation you can defend line by line, and a month end that does not disappear into reconciling a spreadsheet.

How it works in practice

What happens between a deal closing and someone getting paid, and why the working matters more than the total.

1. 1

   The plan is a version, not a document

   Rates, tiers, caps and ramp, with the dates each version applies to. Changing a plan makes a new version and leaves old periods alone.

2. 2

   Deals qualify, and the reason is recorded

   Which transactions count for this period, on which date, under which rule. Splits are apportioned and validated to 100 percent.

3. 3

   The calculation writes down its own working

   Per deal: the plan version, the tier, the rate, the split, the arithmetic, and the amount. The total is just the last line.

4. 4

   A rep reads a statement, not a number

   Attainment, every qualifying deal with its commission line, adjustments with reasons, and the period total.

5. 5

   Disputes happen on a line, not in an email

   A rep queries a specific line, it routes to the plan administrator, and the resolution is recorded against it.

6. 6

   The period freezes on approval

   Later corrections become adjustments in the next period. Nothing silently rewrites a period somebody has already been paid for.

1. 1

   The plan, versioned properly

   Getting the thing everyone argues about into a shape you can reproduce.

   Copy

   In this Helix project, build me a commission calculator.
   
   Start with plans, and get one detail right that causes more disputes than
   anything else. For each tier, I need to say whether the rate applies only
   to the portion of attainment inside that band, or to the whole amount once
   that band is reached. Both models exist in real plans and confusing them
   is the classic commission bug. Make it an explicit choice per tier.
   
   A plan has an effective-from date, a quota period, a base rate, its tiers,
   and any cap. Never edit a published plan version. Editing creates a new
   version, and old periods keep pointing at the version they were calculated
   under.
   
   Then assign reps to plans with a quota, a start date and a ramp. And give
   me a preview: type an attainment figure and show me what it would pay and
   why.
   
   I sign in through Helix, so do not build a login page. Read the signed-in
   user from the runtime. And do not put any key or connection string in the
   code: if this needs to reach another system, tell me and I will create the
   connection in my workspace.

   Worth knowing. Marginal versus whole-amount tiering is the single most common source of commission disputes. Making it an explicit field removes the ambiguity permanently.

2. 2

   What counts, before what it pays

   Qualification, splits and clawbacks, which is where real plans live.

   Copy

   Now decide what actually counts.
   
   Load transactions with their booking, close, recognition and cash dates,
   and let the plan say which event and which date qualifies a deal for a
   period. Record on every row which rule qualified it and on what date.
   
   Handle splits: a deal apportioned across several reps by percentage, with
   the total validated to 100.
   
   And handle clawbacks properly. If a qualified deal is later cancelled or
   refunded, create a negative adjustment in the current open period. Do not
   go back and edit the closed period. That period was correct given what was
   known at the time, and it needs to stay that way or nobody can reconcile a
   payment against a statement.

3. 3

   Show the working

   The requirement people underestimate, and the one that decides your month end.

   Copy

   Now calculate, and treat the working as the output rather than the total.
   
   For each rep and period, store a line per step. Attainment, with ramp
   applied and shown as its own line. Then for each deal: the plan version
   used, the tier the attainment fell in, the rate, the split, the
   calculation performed, and the resulting amount. Then adjustments,
   clawbacks, draws and guarantees, each with a reason and an approver.
   
   The period total is derived from those lines and never entered directly.
   
   Store the derivation as rows rather than computing it on demand. That is
   what lets me answer a question about a period six months after the plan
   changed, which is exactly when it gets asked.

   Worth knowing. A number with no visible derivation produces a dispute from every rep, every period. Answering those costs more than the calculation.

4. 4

   Statements, disputes, and closing the period

   Making it trustworthy enough that people stop rebuilding it in a spreadsheet.

   Copy

   Give each rep a statement: attainment against quota, every qualifying deal
   with its commission line, adjustments with reasons, and the total.
   Downloadable, and readable without an explanation.
   
   Let them query a specific line rather than emailing about the total. The
   query routes to the plan administrator and the resolution is recorded
   against that line.
   
   Add a review step before payment showing period totals by team, the
   largest payouts, and anything that changed since the last run. Then freeze
   the period on approval. After that, corrections become adjustments in the
   next open period, with a reason, never a silent rewrite.
   
   Finally, an export for payroll, and a record of what was exported and
   when.

5. 5

   Connect it to real systems

   The step that turns a working prototype into something with your data in it.

   Copy

   Now connect it to the systems we actually run, so it works on real data
   rather than the rows you seeded.
   
   Anything in angle brackets is a placeholder. Swap it for whatever we use
   instead, and have the app name the connection it wants rather than assume
   a vendor, so changing my mind later is a config change and not a rewrite.
   
   <Salesforce>. Read closed deals with their amounts, dates and splits,
   which is what qualifies a transaction.
   
   <NetSuite>. Check invoices and cash received, if your plan pays on
   collection rather than closure.
   
   <Workday>. Read plan assignments and quotas, and export the approved
   period for payment.
   
   <Gmail>. Send each rep their statement, so a dispute happens on a line
   rather than in a thread.
   
   <Snowflake>. Read closed bookings from the warehouse, where the CRM data
   has already been cleaned up.
   
   <Gusto>. Export the approved period to payroll, and record exactly what
   was sent and when.
   
   <Okta>. Authenticate reps and read the manager relationship, which is what
   lets the app show a statement to its owner and their manager and nobody
   else.
   
   Only write where I have said to write. Everything else is read only.
   
   Do not write a key, a token or a connection string anywhere in the code,
   and do not ask me to paste one. Tell me which connections you need and I
   will create each as an authentication in my Helix workspace. Reference
   them by alias.

   Worth knowing. Every name in angle brackets is a placeholder for whatever you run. Helix holds the credential as a workspace authentication, so the app references an alias and never the secret itself.

6. 6

   Ship it

   The last step of every build: a URL, and the right people on it.

   Copy

   Deploy my app.

   Worth knowing. Your assistant runs helix deploy underneath and the app comes back as a URL. Compensation is among the most sensitive data you hold, so set Access Control before sharing and scope it so a rep sees only their own statement.

What it connects to

This app decides what people get paid, so what it reads and what it writes both matter more than usual.

• Salesforce

  Read closed deals with their amounts, dates and splits, which is what qualifies a transaction.

• NetSuite

  Check invoices and cash received, if your plan pays on collection rather than closure.

• Workday

  Read plan assignments and quotas, and export the approved period for payment.

• Gmail

  Send each rep their statement, so a dispute happens on a line rather than in a thread.

• Snowflake

  Read closed bookings from the warehouse, where the CRM data has already been cleaned up.

• Gusto

  Export the approved period to payroll, and record exactly what was sent and when.

• Okta

  Authenticate reps and read the manager relationship, which is what lets the app show a statement to its owner and their manager and nobody else.

Each line says whether the app reads, writes or both. Anything not described as writing should be read only.

Named systems are the ones most teams actually run, not a list of the only ones that work. Swap in whatever you use.

Each connection is an authentication in your Helix workspace, referenced by alias. The app names the connection it wants and never holds the credential, so nothing here ends up in your code and any of it can be rotated or revoked without a redeploy.

Related guides