How to build a commission data to payroll sync

What matters here

• Show the working per line. A statement with a total and no arithmetic makes every question an investigation.
• Qualify transactions explicitly. Closed-won is not the same as commissionable, and the difference is where disputes come from.
• Hold a disputed line without holding the run. Everybody else should be paid on time.
• Reconcile the total against qualifying revenue before the export. A commission correction after payment is a conversation about somebody trust in the whole plan.
• Version the plan. A statement is calculated against the plan as it was, and plans change mid-year.

Who this is for

You run revenue operations or sales compensation. Commission is calculated in a spreadsheet, queries take days, and the finance team dreads the last week of the quarter.

How it works in practice

What has to happen between a deal closing and somebody being paid for it.

1. 1

   Transactions are qualified against the plan

   Closed-won is a stage; commissionable is a decision with rules behind it.

2. 2

   The plan version in force is resolved

   Because plans change mid-year and a statement is calculated against the one that applied.

3. 3

   Each line is calculated with its working stored

   Rate, tier, split, accelerator and the transaction it came from.

4. 4

   Statements are issued to each rep individually

   Visible before payroll, so a query is raised against a line rather than after a payslip.

5. 5

   Disputes hold that line, not the run

   Everybody else is paid on time and the disputed line is resolved separately.

6. 6

   A reconciliation runs before payroll commits

   Total commission against total qualifying revenue, with any difference explained.

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

1. 1

   Set up and define what qualifies

   Closed-won is a stage, not a commission decision.

   Headless skills build-workflow

   Copy

   Use build-workflow. The systems in play are Salesforce and NetSuite,
   or whatever we run in those seats.
   
   Before calculating anything, define what qualifies. This is where the
   disputes come from:
   
     Does commission accrue on closed-won, on invoiced, or on cash
     collected
     How are multi-year and ramped deals treated
     What happens on a downgrade or a cancellation inside a clawback window
     How are splits handled, and who decides them
     Do renewals commission at a different rate from new business
     How is a deal treated if the owner changed mid-cycle
   
   Write those down first. Every one of them is a question a rep will ask,
   and answering it in code without writing it down is how the plan and the
   calculation drift apart.

2. 2

   Version the plan and resolve the right one

   A statement is calculated against the plan that applied.

   Headless skills build-workflow

   Copy

   Use build-workflow. Hold plans as versioned records with effective dates:
   rate tables, tiers, accelerators, caps, floors and clawback terms.
   
   For every transaction, resolve which plan version applied on the relevant
   date and calculate against that one.
   
   Plans change mid-year. A transaction from March calculated against the
   plan introduced in July is wrong, and it is wrong in a way that is very
   hard to spot and very easy to argue about.
   
   Store the plan version id on every calculated line, so a statement can be
   reproduced exactly even after the plan changes again.

3. 3

   Show the working, line by line

   A number with no arithmetic is a number nobody can check.

   Copy

   For every commission line, store and display: the source transaction with
   a link to it, the qualifying amount, which rule matched, the rate applied,
   the tier at the time, any split and its basis, any accelerator, and the
   resulting amount.
   
   A rep should be able to open a statement and follow the arithmetic from
   the deal to the number without asking anybody.
   
   This is the single change that reduces disputes most. Most queries are
   not disagreements about the plan; they are somebody unable to see how a
   figure was reached, and once they can see it, most of the questions never
   get asked.

   Link each line to the opportunity. A rep who can click through to the deal answers their own question in seconds.

4. 4

   Hold disputes without holding the run

   Everybody else should be paid on time.

   Headless skills tray-gotchas

   Copy

   Use tray-gotchas, then handle disputes properly.
   
   A rep raises a query against a specific line. That line is held; the rest
   of their statement and everybody else's run proceeds.
   
   Route the dispute to the compensation owner with the working already
   attached, so the conversation starts from the arithmetic instead of from
   a request for it.
   
   Resolve as: upheld with a corrected line and an adjustment in the next
   period, or explained with the reason recorded against the line so the
   same question is answered permanently.
   
   Handle: a deal cancelled after commission was paid, which triggers a
   clawback per the plan rather than an ad hoc deduction; a split agreed
   verbally, which needs recording before it can be paid; and a rep who left
   mid-period, whose treatment is in the plan and should not be improvised.

5. 5

   Reconcile before it reaches payroll

   Afterwards every difference is a correction and a conversation.

   Copy

   Before the period is exported to payroll, reconcile:
   
     Total commission against total qualifying revenue, at the expected
     effective rate
     Every rep with qualifying transactions and no commission line
     Every commission line with no qualifying transaction
     Anybody over their cap, or under a floor they are entitled to
     Held disputes still unresolved with the payroll cutoff approaching
   
   Send it to the compensation owner and finance before the export.
   
   Then report per period: total commission, effective rate, disputes raised
   and upheld, days to resolve, and corrections after payment. That last
   number should trend to zero, and it is the honest measure of whether the
   working is actually visible.

6. 6

   Validate, then hand the plans over

   Because the plan belongs to sales leadership, not to engineering.

   Copy

   Run the per-step schema checks and the whole-workflow audit before this
   touches production. Run parallel for two periods against the existing
   spreadsheet and reconcile every difference before trusting it.
   
   Then open the same workflow in Tray Build so revenue operations can
   maintain plan versions, rate tables and qualification rules in the visual
   canvas. Plans change annually at minimum and mid-year more often than
   anybody plans for.

What it connects to

Deals close in one system, money is paid from another, and the plan sits between them.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Questions people ask

Related guides