Introduction
For merchants with subscription products, correctly representing recurring commissions determines transparency, payouts and partner trust. Affilentra Pro connects self-hosted affiliate software with merchant programs and offers roles, tracking as well as commission and billing features. This guide shows, in practical terms, how to track subscription events in Affilentra, set up recurring commission rules, correctly handle proration on plan changes and settle churn or retention bonuses.
1. Establish the foundation: Roles, product and tracking IDs
Before you create rules, check these basic points:
- Create roles: software operator (Admin), merchant (Merchant) and partner (Affiliate). Ensure merchants have access to their program settings.
- Create the product as a subscription: In Affilentra, assign a unique product/subscription ID for each subscription product. This ID must appear in the tracking events so that recurring payments can be attributed to the correct product/partner.
- Subscription ID in the payment stack: Ensure your payment provider includes the subscription ID, invoice ID and transaction ID with every charge event.
2. Track recurring events: Which events do you need?
At minimum, these events should be processed in Affilentra:
- initial_sale (first payment/trial conversion)
- subscription_payment (monthly/annual recurring payment)
- subscription_proration (plan change/partial credit)
- subscription_cancelled / subscription_expired
- payment_failed / chargeback / refund
In practice implement this as follows: your payment provider sends webhooks to the platform's tracking endpoint. Pay attention to the following fields in the payload: subscription_id, transaction_id, amount, currency, event_type, timestamp, invoice_id, customer_id and, for plan changes, additionally previous_plan / new_plan as well as prorated_amount or proration_days.
3. Configure recurring commission rules
Structure commissions into three levels: initial payment, follow-up payments, special bonuses.
- Initial payment: Define a rule for initial_sale (e.g. 30% or a fixed amount). Payout occurs after validation of the conversion.
- Monthly/annual commissions: Create a recurring rule that triggers on each subscription_payment. The rule can be percentage-based (e.g. 10% per charge) or a fixed amount (e.g. €5/month).
- Control dependencies: Allow different rates for trial→paid conversions, upgrades or downgrades. Use product and plan metadata to assign rules granularly.
Technical notes: Use the Subscription ID as the primary key for mapping partners. On first sale, store the partner assignment (e.g., via tracking link or coupon) in the subscription metadata so that subsequent payments are automatically attributed to the correct partner.
4. Handle proration correctly when changing plans
Plan changes often generate prorated amounts. There are two practical approaches to calculating the commission:
- Amount‑based (recommended): The commission is calculated from the actually billed amount. If the payment provider supplies a prorated_amount, the commission = prorated_amount × commission_rate.
- Time‑based: If you want to calculate commissions strictly by usage time, you need proration_days or period_lengths. Example: Pro rata commission = (days_active / total_days) × period_commission.
To reliably represent proration, proceed as follows:
- The payment webhook for plan changes must include prorated_amount and details about previous_plan/new_plan.
- In Affilentra, create a processing rule that is triggered on event_type = subscription_proration and calculates the commission based on prorated_amount.
- Configure idempotency: Check transaction_id and invoice_id to avoid duplicate postings.
Example calculation: commission rate 10%, prorated_amount = 15.00 € → commission = 1.50 €. Document the basis (prorated_amount, previous_period, new_period) in the transaction history for traceability.
5. Churn handling: chargebacks & retention bonuses
Clean churn management covers two aspects: clawbacks (recoveries) on cancellations/refunds and positive incentives for retention.
Clawbacks and adjustments
- On refund, chargeback or subscription_cancelled, Affilentra must create an adjustment entry: negative commission or cancellation flag.
- Policy: Decide whether a refund cancels only the last commission or prorates across multiple periods. Implement the rule as automated adjustment logic that reacts to refund events.
Retention bonuses
- Pay retention bonuses when a partner actively contributes to customer retention (e.g., reactivation after cancellation intent, upsell, successful support intervention).
- Technical implementation: Define a trigger event retention_success (manual or automated by your CRM/support) that initiates a bonus payment. The bonus can be a fixed amount or a percentage of the next charge.
- Tiers: Pay tiered bonuses, e.g., a small bonus for retention >30 days, a larger bonus for >90 days.
6. Reconciliation, reporting and payouts
Set up regular reconciliation processes:
- Export transaction lists including Subscription‑ID, partner, event type, amount, commission and status (paid/adjusted/pending).
- Check open items: failed payments and outstanding chargebacks must be cleared before payout.
- Use Affilentra's billing function to create payout entries. Set payout cycles (monthly, weekly) and define minimum payout thresholds.
7. Testing and best practices
- Test environment: Simulate all relevant webhook events (initial_sale, subscription_payment, proration, refund, cancel) and verify the results in the partner history.
- Idempotency: Check transaction IDs before posting to avoid duplicates.
- Documentation: Store metadata (e.g. original_invoice_id, coupon, marketing asset) for later audits.
- Transparency: Provide partners with a traceable payout history (tracking links, periods, deductions due to refunds).
- Data protection & compliance: Pay attention to storage of customer data according to the GDPR and pseudonymize where possible.
Conclusion and implementation steps
Affilentra Pro provides the necessary infrastructure to model subscriptions, proration and churn logic self‑hosted. In short, the next steps are:
- Create product/subscription IDs in Affilentra and store partner attribution at first purchase.
- Implement webhook integration with the payment provider and send all relevant fields (in particular subscription_id, transaction_id, prorated_amount).
- Configure commission rules for initial and recurring payments; process proration events so that commissions are based on prorated_amount.
- Introduce and automate churn adjustments and retention bonuses as triggered events.
- Perform extensive testing and set up reporting/reconciliation for payouts.
If you are ready to run your affiliate program for subscriptions securely and transparently, choose your entry: Choose entry.
Next step
Try Affilentra yourself
A unified platform that transparently brings together product delivery, tracking, conversion validation, commission calculation and payout along clearly separated roles; option for self‑hosted installation with a perpetual license and no revenue share; merchants retain control over products, terms and marketing assets; partners receive personal tracking links and a traceable payout history.