Full Features Guide

Product: BitCommissions24

Version: 1.0

Last Updated: August 26, 2026

Overview

BitCommissions24 is a native sales commission management application built exclusively for the Bitrix24 CRM platform. It eliminates manual spreadsheet-based commission tracking by automating the full commission lifecycle — from rule definition through calculation, approval, and audit — entirely within your existing Bitrix24 portal.

The Application runs as an embedded iframe application within Bitrix24, communicates with a secure backend powered by Cloudflare Workers, and stores business data in both Bitrix24's native Data Storage and a dedicated Cloudflare D1 database. No external integrations, third-party middleware, or external software tools are required.

Subscription Plans at a Glance

Part 1 — Commission Rule Engine

1.1 Commission Structures

The Application supports five commission structures, each designed to accommodate different compensation philosophies:

STRAIGHT (All Plans)

A straightforward percentage of a selected monetary basis applied to each qualifying CRM deal or transaction.

• Basis options: Gross Revenue, Net Revenue, Profit Margin, Custom CRM Field
• Best for: Simple sales teams, early-stage businesses, volume-based roles
• Example: 8% of deal gross revenue for any closed-won deal above $1,000

SPLIT (Enterprise)

Divides a commission pool across multiple sales representatives on a single deal or transaction, using configurable percentage allocations.

• Supports splits between SDRs, Account Executives, and Sales Engineers
• Each split recipient can have an independent commission rate or flat amount
• Split percentages must sum to 100% or can be configured as independent parallel commissions
• Best for: Team-based selling, co-ownership deals, SDR/AE collaboration models

SPIFF (Enterprise)

A time-limited bonus commission on top of the standard compensation plan, used to incentivize short-term goals.

• Configurable start and end dates for each SPIFF rule
• Can target specific products, product categories, deal stages, or CRM conditions
• Runs in parallel with standard commission rules
• Best for: Product launches, seasonal promotions, inventory clearance, performance contests

BASE_PLUS (Enterprise)

A hybrid model combining a guaranteed base component with a variable commission on top.

• Configurable base salary amount (fixed monetary value)
• Variable commission rate applied above the base
• Supports custom formulas for the variable component
• Best for: New hire ramp-up periods, B2B sales with long cycles, enterprise account teams

TIERED (Enterprise)

A progressive commission structure where rates increase as the representative surpasses defined revenue or performance thresholds.

• Incremental mode: Each tier rate applies only to the marginal revenue within that bracket (like a tax bracket system)
• Retroactive mode: The highest qualifying tier rate applies back to all revenue from dollar one
• Up to unlimited tier brackets configurable per rule
• Tier basis options: Cumulative Revenue, Quota Attainment %, Units Sold, Custom CRM Field
• Best for: Quota-driven teams, accelerator programs, high-volume sales environments

1.2 Commission Calculation Basis

The "basis" determines the monetary value the commission rate is applied to:

1.3 Rule Trigger Configuration

Each commission rule specifies precisely when and for what CRM entity type it activates:

• Supported entity types: CRM Deals, CRM Invoices, Smart Process Automation (SPA) items, and other supported Bitrix24 CRM entity types
• Trigger events: Entity created, entity updated, entity stage changed, entity deleted (for clawbacks)
• Stage-based filtering: Rules can be restricted to fire only when a deal moves to a specified stage or pipeline
• Condition filtering: Full filter builder supporting AND/OR logic trees on any CRM field (numeric comparisons, text matching, multi-select membership, date ranges, boolean flags)
• Priority: Each rule has a priority value from 1–999 controlling evaluation order when multiple rules could match the same event

1.4 Rule Builder — Condition Filters

The rule builder includes a visual filter builder that supports:

• Field sources: CRM entity fields (standard and custom), product row fields
• Operators: equals, not equals, greater than, less than, between, contains, is empty, is not empty, in set, not in set
• Logic grouping: Nested AND/OR groups for complex conditional logic
• Field types supported: Text, Number, Date, Boolean, User reference, Enumeration (list), Money

Examples of filter conditions:

• Deal Amount > 5000 AND Territory = "North East"
• Product Category IN ["Software", "Licenses"] AND Deal Stage = "Closed Won"
• Assigned User IN [specific rep list] AND Probability >= 90%

1.5 Caps, Floors, and Guardrails (Enterprise)

To protect business financials and guarantee minimum rep earnings:

• Commission Cap: Sets a maximum payout amount per commission entry. If the calculated commission exceeds the cap, it is rounded down to the cap value.
• Commission Floor (Minimum Guarantee): Sets a minimum payout amount. If the calculated commission falls below the floor, the floor value is paid instead.
• Caps and Floors can be configured as fixed monetary amounts or as percentages of deal value.
• Multiple rules with overlapping conditions can each have independent caps and floors.

1.6 Commission Locking (Enterprise)

Rules can be configured to automatically lock commission entries after a specified number of days following calculation. Once an entry passes its lock deadline:

• No further status change, amount override, or notes edit is accepted — whether initiated manually, through a bulk recalculation, or through a CRM event that re-matches the same entity against the same rule
• Provides audit-trail protection for finalized periods
• Lock period is configurable per rule (e.g., lock after 30 days)
• There is no exception-basis unlock — a locked entry stays locked

Part 2 — Custom Formula Engine (Enterprise)

2.1 Formula Expression Support

Enterprise subscribers can define commission amounts using a full mathematical expression engine, rather than a fixed percentage:

Supported variables:

Supported functions:

• ROUND(value, decimals): Rounds a number to a specified number of decimal places (defaults to 2).
• FLOOR(value): Rounds a number down to the nearest integer.
• CEIL(value): Rounds a number up to the nearest integer.
• ABS(value): Returns the absolute value of a number.
• MIN(val1, val2, ...): Returns the minimum of 2 to 10 arguments.
• MAX(val1, val2, ...): Returns the maximum of 2 to 10 arguments.
• IF(condition, trueValue, falseValue): Returns trueValue if the condition is truthy, otherwise falseValue (supports logical operators).

Supported Operators & Comparison:

• Arithmetic: +, -, *, /, % (modulo), ^ (power)
• Comparison: >, <, >=, <=, == (equal), != (not equal)

Expression limits:

• Maximum expression length: 500 characters
• Maximum formula depth (nested operations): 20 levels
• Maximum numeric result: 10¹⁵
• Division or modulo by zero safely evaluates to 0 instead of throwing an error.

Security: The formula engine is a sandboxed recursive-descent parser. It does not use JavaScript's eval() function or any dynamic code execution — protecting against injection attacks.

2.2 Formula Iteration Mode (Per Product Row)

When a deal contains multiple product line items, the formula can be evaluated per product row and the individual results summed:

• Apply a different rate based on product type, category, or price point
• Access {quantity} and {price} for each individual product row
• Define per-product rate overrides by selecting specific catalog products and assigning product-specific commission rates

Part 3 — Commission Journal

3.1 Automatic Journal Entry Generation

Every time a qualifying CRM event triggers a matching rule, the Application automatically creates a commission journal entry containing:

• Assigned sales representative(s)
• Commission amount calculated
• Deal/entity reference
• Rule that triggered the calculation
• Commission type and structure used
• Calculation breakdown (basis amount, rate applied, any modifiers)
• Timestamp of calculation
• Data snapshot at time of calculation (deal value, assigned user, product rows if applicable)

3.2 Journal Entry Status Lifecycle

Each journal entry progresses through a defined status state machine:

PENDING → CALCULATED → APPROVED → PAID
                    ↘ DISPUTED
                    ↘ VOID
          ↘ VOID
CLAWBACK (terminal — triggered automatically on entity deletion)

Status transitions are enforced by a state machine — invalid transitions (e.g., PAID → CALCULATED) are rejected.

3.3 Auto-Approval Automation (All Plans)

Administrators can configure rules to automatically approve commission entries that meet defined criteria (e.g., below a certain value, for specific rep groups), reducing manual approval workload.

3.4 Manual Adjustments and Overrides (Enterprise)

Administrators with write access can:

• Create manual commission entries for scenarios not covered by automated rules (e.g., one-off bonuses, referral fees, exceptional deals)
• Override an existing commission amount on any journal entry in CALCULATED or DISPUTED status
• Add notes explaining the reason for an override (recorded in the activity log)
• Manual entries are fully audited and appear in all reporting views

Part 4 — Clawback Detection (Enterprise)

4.1 Automatic Clawback on Deal Deletion

When a Bitrix24 deal is deleted or cancelled after a commission entry has been created, the Application automatically generates a negative commission entry (CLAWBACK status) to reverse the payout.

• Triggered by Bitrix24's deal deletion webhook event
• Configurable clawback window (e.g., only trigger clawback if deletion occurs within 90 days of payout)
• Creates a linked clawback entry referencing the original commission entry
• Original entry remains in the journal for audit continuity

4.2 Distributed Clawback Locking

To prevent duplicate clawback entries during high-concurrency processing, the Application uses a distributed locking mechanism ensuring each clawback is processed exactly once, even if multiple webhook events are received for the same deletion.

Part 5 — Notifications and Automation Actions (Enterprise)

Commission rules can trigger automated in-platform notifications on status changes:

• Notify representative when a new commission entry is created for them
• Notify administrator when a commission enters DISPUTED status
• Notify rep when a commission is approved or paid
• Notification templates are configurable per rule
• Notifications are delivered via Bitrix24's native notification system

Part 6 — Reporting and Analytics

6.1 Commission List View (All Plans)

A paginated, filterable table of all commission journal entries showing:

• Representative name and avatar
• Commission amount and status
• Rule name and structure type
• Associated CRM entity (deal name/ID)
• Calculation date and last updated timestamp
• Quick-access status transition controls

Filtering capabilities:

• By status, representative, rule, date range, commission structure type, amount range

Sorting: By date, amount, status, representative name

6.2 Period Summary Cards (All Plans)

Dashboard cards displaying period-level aggregations:

• Total commissions calculated in the current period
• Total approved and paid commissions
• Commission breakdown by status
• Top-performing representatives by commission earned

6.3 Dashboard — Performance Metrics (All Plans)

The main dashboard provides at-a-glance performance metrics for the selected period:

• Top Performers by commission earned
• Revenue Leaders by total deal value
• Volume Leaders by number of deals closed
• Status Breakdown — pie/bar chart of entries by status
• Efficiency Metrics — approval rate, average commission per deal

6.4 Daily Snapshots (Enterprise)

The Application generates pre-aggregated daily commission snapshots for efficient historical period reporting:

• Daily net payout totals
• Top 3 representatives by commission
• Status count breakdowns (pending, approved, paid, void, disputed, clawback)
• Active representative count
• Previous period comparison figures

Snapshots are generated automatically via a scheduled cron job and can be manually triggered by administrators.

6.5 Metrics by Representative and Rule (Enterprise)

Granular metric records queryable by:

• Representative + period combination
• Rule-specific metrics (commission earned per rule, per rep)

Available metric keys:

• REV — Total revenue basis
• CNT — Commission entry count
• COM — Total commission amount
• COM_PAID, COM_PENDING, COM_APPROVED, COM_DISPUTED, COM_VOID, COM_CLAWBACK — Commission amounts by status
• CNT_PAID, CNT_PENDING, CNT_APPROVED, CNT_DISPUTED, CNT_VOID, CNT_CLAWBACK — Entry counts by status

6.6 Commission Summary (Enterprise)

Period-level aggregation view for administrators:

• Rollup by status across all entries in a period
• Per-representative breakdown
• Per-rule breakdown
• Filterable by period (month, quarter, custom range)

Part 7 — Multi-Currency Support (All Plans)

The Application supports commission calculations across multiple currencies:

• Automatically syncs exchange rates from your Bitrix24 portal's currency configuration
• Commissions are calculated in the native deal currency
• Reporting aggregations normalize amounts to your configured base currency using the portal's exchange rates
• Administrators can manually update exchange rates from within the Application's settings panel
• Exchange rate history is applied per calculation date for accurate historical reporting

Part 8 — Bulk Recalculation (Enterprise)

When rules need to be corrected retroactively or a data issue is discovered:

• Dry-run mode: Preview which journal entries would be affected and what the recalculated amounts would be, without making any changes
• Execute mode: Apply recalculated amounts to all matching entries in the selected scope
• Scoped by: period, representative, rule, or specific entry IDs
• Full audit trail entry created for every recalculated commission

Part 9 — Historical Sales Backfill (Enterprise)

Deals that closed before the Application was installed — or before a rule existed to cover them — never triggered a live webhook, so they never earned a commission. Historical Sales Backfill closes that gap by replaying past CRM records through the exact same pipeline a live webhook uses (rule matching, calculation, journal write), so past sales end up with the same commission entries they would have gotten if their webhook had fired at the time.

• Record selection: The record types eligible for replay are derived automatically from your currently active rules — only entity types and trigger actions (add/update) your rules actually listen for are included
• Date range: Choose a filter (e.g. created date) and a From/To window; the app reports how many CRM records and how many replay actions match before you start
• Self-paced processing: Replays share the same processing queue as live webhooks rather than a dedicated one, paced in small pages so an in-progress backfill never delays real-time commission processing behind a large backlog
• Non-destructive to finished work: Entries already Approved or Paid are left untouched; only Pending/Calculated entries are recalculated, and Commission Locking (Part 1.6) applies the same way it does to live events
• Available for CRM Deals and other supported entity types your active rules cover

Part 10 — Data Export (All Plans)

10.1 Commission Journal Export

Export the full commission journal or a filtered subset:

• Format: CSV (all plans), JSON (Enterprise)
• Fields included: All journal entry fields including representative, amount, status, rule, entity reference, dates, and calculation breakdown
• Filtering: Apply the same filters as the Commission List View before exporting

10.2 Snapshot and Metrics Export (Enterprise)

• Export daily snapshots by period range
• Export metrics totals by representative and period

Part 11 — Administration and Settings

11.1 Settings Panel

Accessible by portal administrators, the Settings panel provides:

General Settings:

• Base currency for reporting normalization
• Fiscal period type (calendar month, calendar quarter, custom)
• Clawback window (days after closure within which a clawback can be triggered)

Webhook Management:

• View currently registered Bitrix24 webhook events
• Manually trigger webhook reconciliation (re-sync registered events with active rule requirements)
• View webhook event log (Enterprise)

Data Storage Health:

• Diagnostic view of Bitrix24 Data Storage integrity
• Self-repair options: Full re-provision, add missing entity properties, or sync D1 references

Currency Management:

• View and update exchange rates for all portal currencies

Data Management:

• Preview or execute batch data deletion by scope (period, representative, rule, or full wipe)
• Supports hard-delete of inactive commission rules

11.2 Event Log Viewer (Enterprise)

A paginated, searchable log of all webhook events received from Bitrix24:

• Event type, entity ID, entity type, processing status
• Rules matched and commission outcomes
• Processing duration
• Cursor-based pagination for efficient navigation of large log volumes
• Filter by status, event type, and date range

11.3 Activity Feed (Enterprise)

A unified, immutable timeline of all commission-related activity:

• Commission created, status changed, approved, paid, disputed, clawback generated
• Manual adjustments and override actions
• Actor identification (administrator or system)
• Per-entry timeline and global administrator feed views

11.4 Token and OAuth Health

• View OAuth token metadata (expiry status, token health indicator)
• Identify and diagnose token refresh failures without exposing raw token values

Part 12 — Security and Access Control

12.1 Role-Based Access

The Application enforces Bitrix24's native user role system:

12.2 Data Isolation

All data stored by the Application is strictly partitioned by Bitrix24 portal identifier (member_id). There is no mechanism by which data from one portal can be accessed from another portal — this is enforced at the database query level, not just at the application layer.

12.3 Encryption

• OAuth tokens: AES-256-GCM encrypted at rest with a per-tenant derived key
• All communications: TLS 1.2+ in transit
• No raw payment card data is stored by the Application

Part 13 — Rule Simulator (All Plans)

The built-in Live Rule Simulator allows administrators to test commission rules before activating them in production:

• Inline simulator panel — embedded within the Rule Builder, auto-reruns as you modify rule configuration
• Full simulator drawer — expandable full-screen simulation view with detailed calculation breakdown
• Input a sample deal value, representative, and other relevant parameters
• View the full calculation breakdown: basis amount → rate applied → modifiers → final commission
• Clawback scenarios, cap enforcement, and floor enforcement are simulated
• Parity warnings are displayed when certain features (e.g., live catalog field rates) cannot be fully replicated at simulation time

Part 14 — Rule Management

14.1 Rule Versioning

• Every rule update creates a new version row, preserving a full history of all historical configurations
• Previous versions are retained for audit purposes and retroactive calculation reference
• Only the current active version is used for new commission calculations

14.2 Rule Lifecycle

14.3 Webhook Auto-Sync

When rules are created, updated, or deactivated, the Application automatically:

1. Derives the set of Bitrix24 CRM events required by all currently active rules
2. Compares against the set of currently registered webhook events
3. Binds any newly required events and unbinds any no longer needed
4. Persists the registered event state to prevent drift

Administrators can also trigger a manual webhook sync from the Settings panel.

Part 15 — Technical Environment

Part 16 — Internationalization (Language Support)

The Application interface is available in:

Language is auto-detected from the browser locale and can be manually switched using the language selector in the application sidebar. All UI labels, error messages, status descriptions, and notifications are localized for each supported language.

Appendix A — Glossary

Appendix B — Feature Availability Quick Reference

_© 2026 BitCommissions24. All rights reserved._