Referral program on Bitrix: where tracking breaks
A referral program on Bitrix breaks not at the idea stage, but at the junction of three subsystems: user identification, storage of the "who referred whom" binding, and reward calculation. While traffic is small, the scheme holds together on a handshake and manual reconciliations.
As soon as the number of partners reaches dozens, and orders begin to be placed in multiple currencies and through different channels, lost bindings, double accruals, and discrepancies with accounting surface.
The most common cause is that the referral binding lives in a cookie or in a session. A user came via a link with a tag, registered a day later from another device, placed an order a week later — and the "partner → client" link is already lost.
If the partner identifier is not recorded in the database at the moment of first touch and not confirmed at registration, reconstructing the chain after the fact is nearly impossible: only web server logs remain, and by that time they have already rotated.
The second point of failure is the moment of accrual. When the trigger is the "order paid" event rather than "order completed and not returned," the program starts paying for purchases the client will return.
The opposite situation is accrual upon shipment without idempotency: a repeated call of the handler during a payment system retry creates a second reward for the same order.
Referral tracking and reward accrual must rely on a unique operation key, otherwise double entries are inevitable.
The third layer of problems is the discrepancy with accounting. A partner reward is not just a record in a table, but a liability with a date, amount, and basis.
If the module calculates bonuses using one logic, while accounting receives an export using another, the difference accumulates over months and surfaces at period closing. Let's break down how this is closed at the architecture level, rather than with patches in handlers.
What a correctly designed program delivers
A correctly designed referral program is first and foremost a deterministic accrual model, not a set of promotions.
When a referral's link to a partner is fixed at the moment of registration and stored as an immutable entity in the database, the share of lost links drops from 8–12% to a fraction of a percent: the dispute over "who brought the client" stops arising, because the source is recorded once and is not rewritten retroactively.
The speed of closing the period is the second measurable effect. If the reward is calculated based on order events (payment, shipment, deal closure) rather than manual reconciliation of spreadsheets, the period closes in hours instead of weeks.
Accounting receives a ready-made accrual register, reconciled with orders and payment statuses, without manual line matching.
The third effect is a reduction in the class of disputed accruals.
When the rules for multi-level payouts, holding periods, and cancellations upon order return are described in code rather than in a policy in words, an entire layer of inquiries — "why wasn't it credited" and "why was it debited" — disappears.
Every accrual has a reference to the event that generated it — this is the transparency that the partner verifies on their own, without emails to support.
We design such modules on 1C-Bitrix taking into account the standard order and cart model, so accruals do not diverge from actual sales, and partner reporting is exported in the form that accounting accepts.
Implementation options: module, customization, external service
The choice between a ready-made module, core customization, an external service, and custom development is determined not by preference, but by where order data lives and how rewards are calculated.
If referral relationships and payout statuses must be consistent with orders, the cart, and payment statuses, the logic must operate inside the platform, otherwise discrepancies between systems will appear.
| Option | When it fits | Limitations |
|---|---|---|
| Ready-made referral program module | A standard scheme: link, coupon, percentage of the order | Rigid accrual logic, difficult to add multi-level structure or custom conditions |
| Core customization | You need your own rules: levels, product categories, deferred payouts | Requires careful handling of updates, otherwise edits get overwritten |
| External service | Referral analytics are needed separately from the platform, multiple sites | Order data syncs with a delay, payout statuses get out of sync |
| Custom development | Non-standard mechanics: partner levels, limits, integration with an accounting system | Longer launch, requires support and documentation |
A ready-made module solves the task in a matter of days, but hits a ceiling as soon as the rules stop being standard. Core customization provides flexibility, however every platform update requires checking that the edits do not conflict with the new version.
An external service is convenient for analytics, but is not suitable as the sole source of truth for accruals.
Custom development is justified when the referral program is part of the business model, rather than an addition to the store. We design the scheme around specific accrual rules so that relationships, statuses, and payouts remain consistent with orders.
How Bitrix referral program implementation works
Implementing a referral program starts not with code, but with an audit of accounting: how orders are currently recorded, where customer-to-partner links are stored, which payment statuses are considered the basis for accrual.
At this stage, we identify bottlenecks — manual reconciliations, duplicate links, lack of change history — and determine what can be reused and what will have to be built from scratch.
Next, we design the data schema: separate entities for partners, referral transitions, accruals, and payouts, along with links to orders and users.
The schema is designed with reporting in mind from the start — so that rewards can be recalculated for any period and every figure can be explained.
- Audit of the current accounting of orders, payments, and customer-to-partner links.
- Designing the data schema: partners, transitions, accruals, payouts, links to orders.
- Setting up accrual rules: percentage, calculation base, fixation periods, cancellation conditions.
- Implementing the partner's personal account with statistics on transitions and rewards.
- Testing accruals on scenarios: partial payment, refund, repeat purchase, order cancellation.
- Reconciling calculated data with actual orders and closing discrepancies.
- Handover: documentation on the rules, access credentials, training of the responsible employee.
Separately, we check how the system behaves on refunds and cancellations — this is where disputed accruals most often arise. Accrual testing is performed on a copy of real data so that before launch you can see how the rules work on partial payments and repeat purchases.
After handover, a regulation remains: who changes the rules, how payouts are recorded, where to view the history. Describe your accounting scheme — we will come back with an estimate and an implementation plan.
What the client receives after launch
Launching a referral program is not just working code, but also a set of artifacts that your team can use to maintain and evolve the system without us.
We hand over everything in a structured form: from configuration to regulations, so that six months later no one has to reconstruct the logic from memory.
- Module documentation — a description of the data structure, the relationships between users, partners, and accruals, as well as extension points for your future tasks.
- Accrual regulations — the rules for calculating rewards, the conditions for triggering them, and the procedure for recalculation and reversal in the event of returns and order cancellations.
- Integration diagram — a map of how the module interacts with orders, payments, users, and external systems, including queues and deferred operations.
- Instructions for the team — how to deploy the module on a staging environment and in production, how to enable and disable the program, where to look at logs, and how to diagnose typical situations.
- Configured setup — working program tiers, rates, referral link and cookie lifetimes, limits, and anti-fraud rules in a ready-to-use form.
- Administrative interface — sections for managing participants, manually adjusting accruals, and exporting partner reports.
- Set of checks — test scenarios for accrual, cancellation, re-registration, and following someone else's link, so that regressions are caught before release.
We separately document the handover of access and the escalation procedure: who on the client's side is responsible for the program and to whom incident-related questions go.
Such a set removes the main risk — dependence on a single person who "remembers how everything works here." Describe your task — we will get back to you with an estimate and a work plan.
Case study: how disputed accruals were cut by three times
The project is an online store on 1C-Bitrix with a partner network: the referral program worked, but accruals were calculated "by eye" and relied on manual reconciliations.
Before implementing a correct accounting scheme, managers spent about 20 hours a month sorting out disputed accruals, and the share of contested transactions reached 18% of the total.
What it was before
The accrual logic lived in checkout handlers and did not account for refunds, partial cancellations, or repeat purchases via the same referral link.
The partner saw one amount in their dashboard, accounting saw another in the report, and every reconciliation turned into a back-and-forth of messages.
A separate problem was "stuck" clicks: if a customer returned via someone else's link, the reward went to the wrong participant.
What was changed
We moved reward calculation into a separate module with an event log: every purchase, refund, and cancellation is recorded as a separate entry tied to a partner and a period.
The accrual is calculated based on an immutable event, not the current state of the order, so a reversal on refund does not break already closed periods.
We added an attribution rule with a window and protection against last-click overwriting, and in the partner dashboard we displayed the same amount as in the accounting report — a single source.
What it became
The share of disputed accruals dropped from 18% to 6% — three times less, and the time spent on reconciliations decreased from 20 to 5 hours a month.
Closing a period now takes a single report run instead of a manual export, and discrepancies between the partner dashboard and accounting have disappeared as a category.
The scheme withstood the growth of the partner network without revisiting the logic — new attribution rules are added via configuration, not by editing code.
How is a module different from core modification?
A module is a separate package that is installed into /local/modules/ or /bitrix/modules/ and registered through the standard connection mechanism.
The core remains untouched: platform and third-party solution updates are installed as usual, while the referral program logic lives in an isolated namespace. Disabling the module is a single operation that leaves no traces in system files.
Core modification means editing the files of the platform itself or components in system directories.
It is fast at the start, but every update turns into a manual conflict resolution: modified files are marked as overridden, and the update either fails to install or overwrites your logic.
After a few releases, maintaining such a modification costs more than the original implementation, and the upgradability of the solution drops to zero.
The risks of core modification do not appear immediately. The very first security patch or major update breaks the accruals, and recovery requires manually reconciling the modified files — while some of the edits may have already been lost during a previous update.
A module eliminates this class of failures: updates are installed as usual, and conflicts are localized within a single package.
There is also an intermediate path — a custom component or event handler without modifying the core.
It is suitable for isolated logic, but a referral program grows with bonuses, tiers, reports, and integration with orders; without a unified structure, such logic spreads across the project. A module provides versioning, migrations, and predictable deployment across multiple sites at once.
The practical criterion is simple: if a solution is planned to be updated for longer than one release, it is a module.
Core modification is justified only where standard extension points physically do not exist, and we record such places in a separate registry describing exactly what is overridden and how it is carried over during an update.
Common technical concerns before starting
Before starting, almost every team asks the same set of questions: will the module break the current site, how to migrate the already accumulated partner data, will the infrastructure handle the load, and can the accrual mechanics be trusted. Below is a breakdown of each point, without generalities.
Is the module compatible with our version of 1C-Bitrix and current components?
The module is built for the current core branch and does not touch standard files — all logic is placed in a separate module with its own tables and event handlers.
If the project already has custom cart or checkout components, we connect to them through events rather than by editing code. This means: core and third-party module updates proceed as usual, and the referral logic remains isolated.
What will happen to the partner data that has already been accumulated?
Existing "client — referrer" links are transferred by a migration script: first a run on a database copy, verification of the number of links and balances, then transfer to production with a rollback in case of discrepancies.
We fully preserve the history of accruals and payouts — partners do not lose what they earned, and you do not have to explain yourself to them after launch.
Will the site slow down under the load from referral calculations?
Accruals and status recalculations are performed not at the moment of a user request, but by deferred scheduled jobs. The partner dashboard serves data from prepared tables, with no heavy queries across the entire order history.
As the number of partners grows, indexes are added and the processing queue is distributed — the site for the buyer works at the same speed.
How are accruals protected from inflation and substitution?
The link to the referrer is fixed once and protected from re-binding, and accrual occurs only on a confirmed paid order.
All operations are written to a log indicating the source, manual balance edits are available only to an administrator with the rights and leave a trace in the history. Disputed accruals can be rolled back selectively, without recalculating the entire program.
Describe your configuration and current partner data — we will return with a compatibility assessment, a migration plan, and a load scheme for your traffic.
Let's discuss your referral program task
To make the estimate realistic rather than an "industry average," we break the task down line by line.
It's important for us to understand how your customer and order tracking is currently set up, where invitation data is stored, which events are considered target events, and how rewards are calculated — a percentage of the amount, a fixed rate, or points.
This determines the module's architecture: where to calculate accruals, how to protect against self-invitations and gaming the system, how to make payouts and reflect them in reporting.
Next, we look at integrations: exchange with 1C for item nomenclature, orders, and settlements, connection with CRM, notifications to participants, a referral's personal dashboard with statistics and accrual history. If some processes are already automated, we'll fit into the existing logic rather than break it.
- Review of current tracking. We look at how users, orders, and partners are set up, where the bottlenecks and duplicates are.
- Locking down the program rules. Tiers, rates, referral link lifetime, conditions for accrual and write-off.
- Designing the data schema. Tables for invitations, accruals, payouts, statuses — accounting for load and database growth.
- Prototype of the key scenario. Clicking the link, registration, order, accrual — we test on real data.
- Development of the module and admin panel. Program settings, manual adjustments, report export, access roles.
- Integrations and exchange. Connection with 1C and CRM so that accruals and payouts reconcile with accounting.
- Tests and handover. We check edge cases, prepare documentation, and train your team.
After the review, we come back with a stage-by-stage estimate, a work plan, and a list of risks. If during the discussion we see a simpler path, we'll say so directly, without pushing unnecessary scope.
Describe the task in whatever format is convenient, and we'll bring in an engineer who handles such projects.