Running an incentive cycle

An incentive cycle is the routine you repeat for every period of an approved incentive plan: check that every member has a quota, make sure their performance has been captured, run Process Compensation on the period, review and adjust the results, mark them paid, and close the period. This page walks that routine from start to finish on a plan that is already built. The plan itself, with its lines, targets and slabs, is described on Incentive plans. Each step below links to the page that covers its records in full.

Overview

A cycle touches five kinds of record, all tied to one incentive period:

When to use it

• At the start of a period, to confirm that quotas are in place.
• During the period, to keep performance capture complete.
• At the end of the period, to calculate, review and pay the incentives.
• After a late document or a quota correction, to recalculate a period that is still open.

How xMatix handles it

• Periods already exist. xMatix cut the plan's window into periods when the plan was first saved. You never create the next period: it is already on the plan's Compensations tab with Status Draft.
• Quotas are generated or imported. A target whose Target Value Type is Fixed Value, Value Across Periods or Value Across Resources generates every member's quota for every open period in the background, and again when members change. Other quotas are imported.
• Performance comes from two sources. Targets linked to a KPI configuration read that configuration's KPI Data, which accrues when the source records are saved (or on a schedule). All other targets read Performance KPI records, which are written only when someone runs Perform KPI Calculation on an order or invoice. Each document is counted once.
• Nothing is calculated on a schedule. Compensation is produced when someone runs Process Compensation on the period. It finds or creates the period's compensation record, adds a line for each member who has none, clears and re-scores every line that is not yet paid, sets the header's Total Incentive Amount and sets the period's Status to Calculated.
• Lines also score when saved. Saving a compensation line re-runs the incentive engine for that line, but does not change the header total. Only Process Compensation writes the total.
• How a line's amount is combined. Each incentive line of the plan that qualifies earns its own amount from its slabs. The plan's Compensation Eligibility then combines them: the largest for Any One Max, the smallest for Any One Min, and the sum when it is empty or Formulae. See Compensation slabs.
• Paid is final. A line marked Is Compensation Received is never re-scored, though its amount still counts in the total.
• Closing is optional. A period whose Status is Approved or Posted cannot be processed again and its quotas are no longer regenerated. Neither value is in the shipped Status picklist, so an administrator adds them if you want to lock periods.
• No payout posting. The cycle creates no journal, payment or payroll entry. The money is paid outside xMatix or through a process you build.

Prerequisites

• An incentive plan with Status Approved, with at least one member (Incentive Resource), and with incentive lines, targets and compensation slabs. A plan that is not Approved is never scored.
• The Process Compensation button on the incentive period page and permission to run it. Neither is there for ordinary users out of the box (see Configuration).
• For targets read from Performance KPI records: the Perform KPI Calculation button on orders and invoices and permission to run it.
• Edit access to Compensation and Compensation Line for the people who review results.

Procedure

Step 1 — Check the period and its quotas

1. Open the Rewards app, select Incentive Plan and open the plan.
2. Select the Compensations tab. The Incentive Period list shows each period with Date From, Date To and Status. Find the period you are about to run; it should be Draft (or Calculated if it has been processed before).
3. Select the plan's Targets by Resources tab. Pick a KPI configuration in the drop-down. The grid shows members as rows and periods as columns.
4. Check that every member has a non-zero quota in the period's column. A cell showing — has no quota, and the grid cannot create one.
5. To change a value, type over it and click Save (n). The message Saved n change(s) confirms it.

To fill a — cell, regenerate the target's quotas or import them (see Member quotas). A member with no quota, or a quota of zero, cannot qualify on that target.

Step 2 — Capture performance during the period

What you do depends on how each target is measured:

• Targets without a KPI configuration (Sale Amount, No Of Invoices, Sale Order Amount and the other built-in target types). When an order or invoice is final, open it and select Perform KPI Calculation in the page header. The document's KPI Calculated field is then set, and it is never counted again. Run it on every document that should count. See Performance KPI.
• Targets with a KPI configuration. Nothing to click: KPI Data accrues when the configured records are saved, according to the configuration's Trigger Event, or when the scheduled accrual job runs. See KPI configurations.

A document counts in the period whose Date From and Date To contain its date. Check the captured figures with the Rewards reports (for example New KPIs Report) before you process the period.

Step 3 — Process compensation

Do this once the period has ended and its performance is complete.

1. On the plan's Compensations tab, open the period.
2. Click Process Compensation.
3. Refresh the page. The period's Status is now Calculated.

If the run is refused, a message explains why (see Common problems) and nothing changes.

The period now has one compensation record with Status Draft and one Compensation Line per member. The record is named from the COMP numbering series, not after the period, so find it on the Compensations list by its Incentive Period column.

If your administrator has not enabled Process Compensation, a compensation record can be built by hand instead. See Build a record by hand.

Step 4 — Review the results

1. In the Rewards app, select Compensation and open the period's record. The header shows Total Incentive Amount.
2. In the Compensation Line list, open each member's line.
3. Compare the achieved figures (such as Sale Amount, No of Invoices or Achieved Value) with what you expect. They show exactly what the engine counted.
4. Check the Incentive Amount, and any Gifts, Points, Scheme or Discount Group the slabs awarded.

If a figure is wrong, fix the input, not the line: the member's quota, the performance records or the plan. Then run Process Compensation again (Step 3). Every unpaid line is re-scored and the total is refreshed.

Step 5 — Record agreed changes

1. On a line, enter an agreed figure in Overre Incentive Amount (the misspelt on-screen label of Override Incentive Amount). Enter 0 to pay nothing.
2. Optionally set the line's Status to Rejected for your records. Status does not change the total, so use an override of 0 to exclude a member.
3. Save the line.
4. Run Process Compensation again so that the header total uses the overrides.

Overrides, line Status and Is Compensation Received are never changed by a run.

Step 6 — Mark paid and close the period

1. When the payout has been made, open each line and tick Is Compensation Received. Later runs leave the line exactly as it is.
2. Optionally, click Edit on the compensation record and set its Status to your sign-off value. The shipped Status picklist is empty, so your administrator adds the values first.
3. Optionally, close the period by setting its Status to Approved or Posted (both have to be added to the picklist, and an Edit button to the period page). From then on, Process Compensation refuses the period.

Step 7 — Move on to the next period

Nothing needs to be created. The next period is already on the plan's Compensations tab, and generated quotas are already in place for it. Repeat from Step 1.

Mobile

Compensation records and their lines can be opened in the Rewards app on the field app, where a record's lines appear in an editable grid. Run the cycle's other steps on the web. See Compensation records.

Fields

These are the fields you work with during a cycle. The full field lists are on the linked pages.

Business rules

• Process Compensation checks. The period must not be Approved or Posted, must belong to a plan, the plan must be Approved, and the plan must have at least one member.
• One record per period. A run reuses the period's oldest compensation record and matches lines to members by Incentive Resource.
• What a run recalculates. Every unpaid line of a current member is cleared and scored again from the current quotas, performance and plan. Lines of people who are no longer members are left as they are and left out of the total.
• Saving a line. A save scores the line again but never updates the header total, and a save outside a run does not clear the line's earlier figures first.
• Lines without a plan or period. A line with no Incentive Plan or no Incentive Period is saved without being scored.
• Late documents. A document whose performance is captured after a run does not change the lines on its own. Run Process Compensation again while the period is open.
• Changed documents. Perform KPI Calculation counts a document once. Later changes to it, or its cancellation, do not reach the Performance KPI records; correct those records by hand and process the period again.
• Closed periods. Approved and Posted periods cannot be processed again and get no regenerated quotas. A grid edit or import can still change their quotas, so avoid that.

Example

A distributor pays its six field reps a monthly incentive on invoiced sales. The plan runs from April 2026 to March 2027 and is Approved.

1. On 28 April the sales operations lead opens the plan's Targets by Resources tab and confirms that each rep has a quota of 500,000 for May - 2026.
2. During May, the billing team runs Perform KPI Calculation on each invoice as it is finalised.
3. On 2 June the lead opens May - 2026 and clicks Process Compensation. The period becomes Calculated, and a compensation record numbered from the COMP series shows six lines and a Total Incentive Amount of 38,400.
4. One rep disputes a returned order. The lead and the rep's manager agree on 4,500 instead of 6,200. The lead enters 4,500 in Overre Incentive Amount, saves, and runs Process Compensation again. The total becomes 36,700.
5. Finance pays on 10 June. The lead ticks Is Compensation Received on all six lines and sets the period's Status to Approved, a value their administrator has added. May is now closed, and June is already waiting on the plan.

Training

Practice exercise

In a sandbox where an administrator has added Process Compensation to the incentive period page and Perform KPI Calculation to the invoice page:

1. Create a monthly Resource plan with one member, one incentive line, a Sale Amount target with Target Value Type Fixed Value and Value 10,000, and one slab with Compensation Type Fixed Amount whose From % is 50. Set the plan to Approved.
2. Record an invoice for the member for 6,000, dated in the first period, and run Perform KPI Calculation on it.
3. Run Process Compensation on the first period.
4. Enter an Override Incentive Amount of 0 on the line, save, and run Process Compensation again.

Expected result: after step 3 the period is Calculated and the line shows a Sale Amount of 6,000 and the slab's amount. After step 4 the header's Total Incentive Amount is 0 while the line's Incentive Amount still shows the computed figure.

Quick reference

• Periods exist already; start each cycle by checking quotas in Targets by Resources.
• A — cell means no quota; generate or import it.
• Run Perform KPI Calculation on each final order or invoice. Each counts once.
• Process Compensation scores the period; nothing runs on a schedule.
• Re-run Process Compensation after any correction. Saving a line never updates the total.
• Override Incentive Amount wins in the total; enter 0 to exclude someone.
• Tick Is Compensation Received once paid; the line is then frozen.
• Approved or Posted closes a period, once an administrator adds those values.

Permissions

A user without the server-action grant cannot run the action even if the button is on the page. Because reps have full access in the shipped profiles, reduce Incentive Resource Target, Compensation and Compensation Line to read-only for profiles that should only see their results. See Security profiles.

Configuration

Set these up once, before the first cycle. Each is described in full on Rewards configuration.

• Process Compensation button. Add ProcessCompensation to the page header of the Incentive Period View layout and grant it on the security profiles of the people who run payouts.
• Perform KPI Calculation button. Add PerformKPICalculation to the OrderView and Invoice View page headers and grant it.
• Period Edit and closing statuses. Add Approved and/or Posted to the Incentive Period Status picklist, spelled exactly so, and add Edit to the Incentive Period View page header.
• Compensation Status values. Add your sign-off states, plus Draft, to the Compensation Status picklist under Setup → Design Studio → Entities → Compensation.
• Scheduled KPI accrual. For KPI configurations whose Trigger Event is Scheduled, add a schedule for the job Accrue KPI configuration data under Setup → Platform → Monitoring → Jobs.
• Background jobs. Member enrolment and quota generation run as the jobs Enrol incentive plan members and Generate incentive target quotas in the Incentives category of the same Jobs screen; check them there if quotas are missing.
• Numbering. Compensation records use the COMP series and lines the COML series. See Document numbering.

Common problems

I can't find Process Compensation on the period page

The shipped period page has no header buttons. An administrator adds ProcessCompensation to the Incentive Period View layout and grants the action (see Configuration).

"The incentive plan must be Approved before its compensation can be processed."

Set the plan's Status to Approved, then run Process Compensation again.

"The incentive plan has no members (Incentive Resources) to compensate."

The plan has no members. Check its enrolment on Plan members, then run again.

"The period is Approved; a closed period cannot be re-processed."

The period has been closed. If it really must be recalculated, an administrator sets its Status back to Calculated or Draft.

"The period is not linked to an incentive plan."

The period has no Incentive Plan, which happens with imported periods. Set the plan on the period, or import it again with the plan.

The total did not change after I edited a line

Saving a line never updates the header. Run Process Compensation on the period again.

A late invoice is not in the results

Run Perform KPI Calculation on the invoice, then run Process Compensation on the period again, as long as the period is still open.

A member's line shows nothing

Check, in this order: the member is on the plan, has a non-zero quota for this period, and has performance dated inside the period. See Troubleshooting rewards.

Common questions

When exactly is compensation calculated?

When someone runs Process Compensation on the period, and again for a single line whenever that line is saved. There is no schedule: if nobody runs it, a period has no compensation. Each run recalculates every unpaid line from the current quotas and performance and refreshes the header total, so run it at the end of the period and again after any correction. Saving a line alone recalculates only that line and leaves the header total as it was.

Targets changed mid-period — what happens?

Nothing changes on existing lines until the period is processed again. The engine always reads the current quotas, so run Process Compensation on the period after a quota correction and every unpaid line is scored against the new values. Lines already marked Is Compensation Received keep their old figures. In a period that is Approved or Posted, generated quotas are no longer updated and the period cannot be processed again.

Can I run the same plan for the next period without rebuilding it?

Yes. All of the plan's periods were generated when it was first saved, and generated quotas cover every open period. For the next period, check the quotas, capture performance and run Process Compensation on that period. Periods are not added when you extend the plan's dates; see Incentive periods.

Does the cycle pay anyone?

No. A compensation record creates no journal, payment or payroll entry. You pay outside xMatix, or through a process your administrator builds, and record it by ticking Is Compensation Received on each line.

Related topics

• Incentive plans
• Incentive periods
• Member quotas
• Performance KPI
• Compensation records
• Compensation slabs
• Rewards configuration
• Tracking incentives
• Troubleshooting rewards