Rebate calculation engine rules¶
Mechanical rules for how the engine turns a deal's rebate elements into payment lines. For what each rebate type pays, see the rebate types and banding reference; for the operational view (progress, logs, reruns), see the rebate calculation concept page.
Which elements calculate¶
Only rebate elements on the deal flagged to calculate are processed. Each element is processed independently: its own dates, periods, member list, streams, and banding.
Element dates are clamped to the deal¶
An element may carry its own date range restriction. Dates outside the deal are corrected and the correction is logged:
- Range start missing, invalid, or before the deal start → the deal start date is used.
- Range end missing, invalid, or after the deal end → the deal end date is used.
- No date restriction → the element runs for the whole deal.
Period blocks¶
The element's payment period sets the calculation block length in months:
| Period | Months per block |
|---|---|
| monthly | 1 |
| bimonthly | 2 |
| quarterly | 3 |
| six-month | 6 |
| annual | 12 |
| biannual | 24 |
| three-year | 36 |
| five-year | 60 |
Blocks start at the element's start date and step forward one block at a time until the end date. A block's end date is clamped to the element end date, so the final block can be short. Period names are "Period 1", "Period 2", and so on, in order.
Participating members¶
- No member restriction on the element → every participant of the deal.
- Simple restriction → the listed member companies only.
- Advanced restriction → include/exclude lists which may name companies directly or contact groups (expanded to their member companies at calculation time, and always limited to the site's member companies).
The participating member count also matters for equal-split lump sums — see output types in the rebate types and banding reference.
Turnover streams¶
Each element declares which figures streams feed it. An element with no input and output streams fails calculation — the engine cannot proceed.
| Stream | Role |
|---|---|
| Input sources | Turnover measured to decide the band / level hit |
| Output sources | Turnover the rebate is actually paid on |
| Currency sources | Turnover used to express the effective rate; defaults to the output sources when not set |
Input and output are often the same streams; when they differ (or when a strung modifier applies to the output), the engine gathers them separately. Turnover is totalled twice per block: for the whole group and per member.
The effective rate stored on every payment line is:
rebate payable after adjustments ÷ currency-stream turnover × 100
(zero when there is no currency turnover).
Estimated (OTE) values¶
Alongside actuals, each line carries on-target-earnings values — the same calculation fed by projected turnover: OTE value, OTE throughput, and OTE payable. These refresh on every projection run. The engine records the last date actual figures exist; a line whose period extends past that date is marked as a mix of actual and projected. A site setting (minimum projection month) can extend projections past the deal end when the deal is close to finishing.
Where results are stored¶
| Run type | Destination |
|---|---|
| Live | Rebate payment lines (updated in place per element + member + period; paid status preserved; new lines inserted) |
| Projection | Projection lines, then copied onto the live lines' OTE columns |
| Simulation | Temporary tables only |
Every line records: the deal, element, member, period from/to and name, group and member throughput, rebateable throughput, rebate value and amount, payable (after adjustments), member-facing value/amount/payable, OTE values, input/output types, payable-to, supplier, currency turnover, effective rate, and the figures-last date used.
After a live or projection run the deal's rebate lines are re-indexed for search, and a live run automatically triggers a projection run so OTE values stay current.
Payment adjustments after the fact¶
When the amount actually paid differs from the calculated total, the engine can distribute the difference across the earnings lines in three ways for review: average (equal share per line), pro-rata (in proportion to each line's share of rebateable turnover; lines with zero turnover get nothing), and VAT (line value plus 20%).