Partner programme & commissions
Overview
This area manages sales partners, attributes revenue to them and settles commissions from it. Three things belong together: the partner (who referred), the attribution (which revenue is theirs) and the settlement (what gets paid out).
Attribution happens through referral codes. Revenue without a code stays unattributed — deliberately: a guessed attribution ends up as a wrong payout.
Core tasks
Create a partner. In the partner list you define master data, role and payout terms. One or more referral codes belong to each partner.
Share referral links. A referral of type link shows its address in the partner detail view, ready to copy. Whoever opens it lands on the target set under Referral programme (your website); the landing is recorded on the referral, and the browser remembers the partner until the code expires, at most as long as the programme's attribution window (default 90 days, see Settings & permissions). If the visitor then registers in the customer portal, the referred customer is recorded on the referral — their later invoices carry the partner's commission for as long as the programme's attribution period runs (counted from the customer assignment; unlimited by default). The Referrals tab shows the end date in the column Attributed until.
Attribute revenue. When revenue arrives through a referral code, it is credited to the partner. The partner detail view shows the attributed revenue and the resulting commission. A sale belongs to exactly one referral — a second code on the same invoice (or its order) is rejected. If several partners referred the same customer, the setting First click wins decides: off means the last click before the purchase counts.
Maintain commission rules. In the partner detail view, tab Rules, the rules determine how revenue becomes commission — as a percentage (of net or gross) or a fixed amount, optionally capped, for all sales or only a customer's first order. The scope decides what a rule applies to: an item, a category (including its subcategories) or all of the partner's revenue. Item and category rules calculate per invoice line: each line gets the most specific matching rule — item before nearer category before parent category before the partner rule; on a tie the higher revenue tier wins, then the higher priority. For this, the net of the attribution is distributed proportionally across the lines; a fixed amount counts once per rule.
Revenue tiers. From partner revenue turns a rule into a tier: it only applies once the partner has referred at least this revenue in the current calendar year (or month) — the current revenue included. Several tiers form a scale, say 5 % from the first euro and 8 % from 10,000 €; the highest tier reached applies. Independently, the fixed tier on the partner works as before: a rule with a tier set applies only to partners with exactly that tier. Rules can also come from other modules — the commission engine takes them in through an interface for rule sources and selects by the same order.
Programme overview. At the top of the partner list, the programme overview shows for this month, last month or the year the referred revenue (net), commissions per state — open, earned, paid out — and the top partners by revenue. The same figures are available as the tile Partner programme for the dashboard.
Settle and pay out. A settlement run collects the open commissions of a period into one settlement. The settlement is first approved and then paid out with Pay out — two steps, so a payout never happens by accident. Only Pay out makes the amount final; after that every line takes its payment channel, which the run records from the partner record when bundling (column Payment channel in the run):
- SEPA payment run — partners with payout method SEPA and a stored IBAN appear in the
payment proposal of accounting as a Commission line and go through the same payment run and the same SEPA file as your supplier invoices. Once the payment run is marked as executed, the line shows "transferred on …". Without an IBAN the commission is listed as blocked in the proposal instead of silently missing. Seeing it in the proposal additionally requires affiliate.settlement.run.
- PayPal file — for partners with payout method PayPal, PayPal file in a paid run downloads a mass
payment file for PayPal Payouts (recipient address, amount, currency, reference, note; no header row). If a partner has no PayPal address, the message names them.
- Payroll export — internal partners with a linked employee receive their commission as a wage type
in the payroll export of the payout month (wage type CSV and DATEV LODAS, unit euro). No credit note is created for them — salary is not a credit note. Freelancers are not part of the payroll export; their commission follows the payout method.
- Manual — without a payout method the run's payout CSV remains (one line per partner, with a
Payment channel column).
The document depends on the payout mode: credit note and self-billing each create a credit note draft in invoicing (for self-billing labelled "Provisionsabrechnung im Gutschriftverfahren"), partner invoice creates no document — the partner invoices you. Do not additionally pay the partner invoice as an incoming invoice if the commission already goes through the payment channel.
What the partner sees in the customer portal. If the partner has portal access, Partner programme shows their open, approved and paid-out commissions, their statements and their referrals — only their own. A statement only appears there once it is approved; drafts stay internal (customer portal).
Cancellation, partial credit and return. If the invoice is cancelled in full, its commission that has not yet been paid out becomes reversed. A partial credit note (invoice correction) or the credit note of a return reduces the commission proportionally: crediting 25 % of the net amount creates a counter-entry of −25 % of the commission with the credit note number as its reason. It matures together with the original (open while the invoice is open) and, after a payout has already happened, is deducted in the next settlement run. A balance of zero or below is never paid out but carried forward; several credit notes together reduce at most the whole commission.
Fields in detail
Partner
| Field | Required | Values / format | What it does |
|---|---|---|---|
Business partner businessPartnerUlid | yes | an existing partner | Who the partner is. Address and contacts come from there — a partner is a role, not a second address record. |
Partner number partnerNumber | no | text, max. 50 characters | Your number for the partner. |
Type partnerType | no | affiliate, reseller, internal, referrer | What kind of partnership — for classification, reporting and payout (internal: via the employee). Which rule applies is decided by scope, tier and priority of the rules. |
Tier defaultTier | no | text, max. 30 characters | Fixed commission tier of the partner: rules with the same tier apply only to partners of that tier. |
Payout mode payoutMode | no | credit note, self-billing, partner invoice | How settlement works. Self-billing means you produce the statement in the partner's name — it spares them an invoice but requires their agreement. |
Payout method payoutMethod | no | SEPA or PayPal | How payment is made — and it takes effect: SEPA partners appear in the accounting payment run, PayPal partners in the PayPal file. Clear the field for manual (payout CSV). |
IBAN payoutIban | for SEPA | valid IBAN | Account for the SEPA payment run. Stored encrypted; in the detail view only managers see it in full, others the last four digits. Leaving it empty keeps the stored IBAN. |
BIC payoutBic | no | 8 or 11 characters | Bank identifier; not needed for SEPA within the euro area. |
Account holder payoutAccountHolder | no | text, max. 140 characters | Only if the account is not held in the partner name — it is the recipient in the SEPA file. |
PayPal address paypalEmail | for PayPal | e-mail address | Recipient in the PayPal file. |
Minimum payout minPayoutAmount | no | amount, 0 or more | From what amount payout happens. Below it the commission stands and keeps growing — which saves transfers of a few euros. |
Status status | no | active, paused, blocked | Whether the partner may refer and settle. |
Linked employee linkedEmployeeId | for type internal | an employee | For type internal the employee whose sales commission this is: it is then paid as a wage type through the payroll export instead of the payout method. An unknown employee is rejected. |
Commission rule
| Field | Required | Values / format | What it does |
|---|---|---|---|
Rate type and value rateType, value | yes | percent or fixed amount | How much commission arises. A percentage is calculated on the net or gross of the attribution (or the line). |
Scope scope | no | partner, product, category | What the rule applies to. Product and category work per invoice line and need their reference. |
Product/category refId | for product/category | item or category | The rule's reference; a category includes its subcategories. |
Trigger trigger | no | sale, lead, recurring | On which occasion the rule applies: sale on the first sale, lead per qualified lead, recurring only on subscription renewals. |
Applies to appliesTo | no | all sales, first order only | First order only is the new-customer commission. |
Basis basis | no | net, gross | What the percentage is calculated on. |
Cap capAmount | no | amount | Maximum per rule and sale. |
From partner revenue minRevenueAmount, revenuePeriod | no | amount; calendar year or month | Revenue tier: the rule only applies from this referred revenue in the period. |
Tier tier | no | text | Only for partners with the same fixed tier. |
Priority priority | no | number | Decides when the rank is otherwise equal. |
Valid from/to validFrom, validTo | no | date | The day of the attribution counts. |
Also on subscription renewals recurring | no | yes/no | A sale rule then additionally pays on every paid subscription renewal invoice of the referred customer — as long as the subscription runs. With the trigger recurring the switch is always on; with lead it does not exist. If several rules match a renewal, the most specific one wins as always, then the higher priority. First order only applies to the first sale, not to renewals. |
Active active | no | yes/no | An inactive rule stays stored but does not apply to any new attribution. |
Settlement run
| Field | Required | Values / format | What it does |
|---|---|---|---|
Period from periodFrom | yes | date (YYYY-MM-DD) | First day of the period whose open commissions the run bundles. |
Period to periodTo | yes | date (YYYY-MM-DD), not before Period from | Last day of the period (inclusive). If it lies before the start, the run is rejected. |
Settings & permissions
- Read and programme overview:
affiliate.partner.view - Partner master data (role, referral codes, payout terms):
affiliate.partner.manage - Commission rules and attribution:
affiliate.commission.manage - Run, approve and pay out settlements:
affiliate.settlement.run
The module is gated by the flag module.affiliate. With it off, navigation and endpoints disappear.
Under Affiliate & commission → Referral programme you decide whether the first or the last click wins, where referral links lead (empty = home page) and how long the browser remembers the partner after the click — the attribution window (affiliate.cookie_days, 1–730 days, default 90). An earlier end on the individual referral wins.
Also there: the attribution period of referred customers (affiliate.attribution_days, 0–3650 days, default 0 = unlimited). It counts from the customer's assignment to the referral; afterwards their follow-up sales no longer earn the partner commission. This sets up programmes such as "12 months of commission on every referred customer" without maintaining an expiry date on each referral. And the wage type for internal commission (affiliate.payroll_wage_type, default 300) — the number under which internal sales commission appears in the payroll export; agree it with your payroll office.
The programme settings require platform.settings.manage.
FAQ & troubleshooting
Revenue appears with no partner. Then it carried no referral code. Attribution can be set on the revenue afterwards if you hold the commission permission.
Attribution is rejected with "already attributed via another referral code". The sale already belongs to another partner. There is only one commission per sale — if the first attribution is wrong, correct it there.
The commission differs from what was expected. Check which rule applied: scope (item, category, partner), the revenue tier reached and the point in time of the attribution decide, not today's rule set.
A SEPA commission is missing from the payment proposal. The settlement run must be paid, the partner needs an IBAN (otherwise the line is listed as blocked), and besides the payment run permission you need affiliate.settlement.run. If the commission is already in an open payment run, it is not proposed a second time.
The PayPal file reports a missing address. Add the PayPal address in the partner detail view and download the file again.
A settlement can no longer be changed. After approval it is fixed — by design. Corrections run through a new settlement.