Kowal_Affiliate - installation and configuration guide

This document describes how to install, enable, and perform the initial configuration of the Kowal_Affiliate module for Magento 2. It covers both technical requirements and practical steps required to launch an affiliate program in the store.

1. System requirements

The module is intended for:

• Magento Open Source / Adobe Commerce 2.4.7+
• PHP 8.2 or 8.3

The Magento project should have at least the following modules available:

• Magento_Store
• Magento_Cms
• Magento_Customer
• Magento_Email
• Magento_Quote
• Magento_Sales
• Magento_SalesRule
• Magento_Backend

2. Installation methods

The module can be deployed as a standard Composer package.

2.1. Installation via Composer

The module is distributed as a Composer package. An example process looks like this:

composer require kowal/module-affiliatebin/magento module:enable Kowal_Affiliatebin/magento setup:upgradebin/magento setup:di:compilebin/magento cache:flush

2.3. Production mode

If the store runs in production mode, after installation it is recommended to also run:

bin/magento setup:static-content:deploy

3. What the module creates during installation

During installation, the module:

• creates its own database tables related to affiliation,
• extends quote and sales_order with affiliate fields,
• adds customer attributes used for affiliate management,
• creates a default CMS page for the partner program,
• prepares system configuration and cron jobs,
• registers email templates and admin panel assets.

3.1. Default CMS page

After installation, an example partner program page is created:

identifier: affiliate-programtitle: Affiliate Partnership Program

The page is generic and can be used in production after minor content personalization.

The patch is idempotent:

• if a page with the given identifier already exists, the module will not overwrite it.

4. Where to find module configuration

The configuration panel is available at:

Stores -> Configuration -> Affiliate Program

Main sections:

• General
• Commission
• Payouts
• Affiliate Portal
• Notifications
• Fraud
• AI
• Reporting

5. Initial configuration after install

After enabling the module, the following configuration order is recommended:

1. enable the module globally,
2. configure affiliate registration,
3. configure commissions and hold period,
4. set the minimum payout threshold,
5. fill in affiliate portal content,
6. configure admin notifications,
7. optionally configure AI,
8. run a test for registration, affiliate click, and order attribution.

6. Detailed configuration

6.1. General

Enable Module

Global module toggle.

If disabled:

• affiliate tracking should not work,
• the registration form should not work,
• commissions and payouts will not be processed.

Recommendation:

• Yes in production after testing is complete,
• No only to temporarily disable the program.

Enable Affiliate Registration

Enables the affiliate application form on the storefront.

If disabled:

• new partners cannot self register,
• the administrator can still manually mark a customer as an affiliate.

Tracking Cookie Lifetime (days)

Defines the lifetime of cookie based attribution after clicking an affiliate link.

Examples:

• 30 for a standard affiliate program,
• 7 for short campaigns,
• 60 or 90 only if allowed by your program terms.

Default Redirect Path

Fallback path used when the tracking link does not include a valid target.

Examples:

• /
• promotions
• catalog/category/view/id/12

6.2. Commission

Enable Commissions

Enables commission calculation for affiliate orders.

If disabled:

• attribution can still be stored,
• but no commission table entry will be created.

Default Commission Rate (%)

Default percentage commission rate.

Example:

• 10 means a 10 percent commission on the current calculation base.

Commission Hold Period (days)

Number of days a commission remains in pending status.

After this period, cron can automatically approve the commission.

Recommendation:

• 14 as a safe default,
• 0 only for very simple programs with no return risk.

6.3. Payouts

Enable Payouts

Enables the payout workflow for affiliates.

If disabled:

• the partner cannot submit a payout request,
• the administrator can still review commissions but cannot process payouts in the module.

Minimum Payout Amount

Minimum balance required to request a payout.

Examples:

• 100
• 250
• 500

6.4. Affiliate Portal

This section controls the content shown in the affiliate dashboard.

Dashboard Intro

Short description at the top of the affiliate dashboard.

It should explain:

• where to find the affiliate link,
• where to see commissions,
• how the dashboard works.

Program Rules

Visible partnership rules for affiliates.

Best practice:

• one rule per line,
• clear and unambiguous statements.

Banner Title

Default title for an example promotional asset.

Banner Subtitle

Short description below the banner title.

Banner Target Path

Default target path for affiliate links and banners.

Examples:

• /
• promotions/spring
• catalog/category/view/id/24

6.5. Notifications

Enable Notifications

Enables the internal notification system and notification queue.

Admin Notification Email

Administrator email address that should receive the most important operational messages.

If left blank:

• the module may use Magento general email as a fallback in selected flows.

Notification Log Retention (days)

Defines how long notification log entries should be stored before cleanup.

6.6. Fraud

Enable Fraud Checks

Enables basic anti fraud checks.

Block Self Referral

Blocks commission when the ordering customer is also the affiliate attributed to the same order.

6.7. AI

The AI section is optional and not required for the core affiliate program.

Enable AI

Main toggle for AI features.

OpenAI API Key

API key used to communicate with OpenAI.

The field is stored in encrypted configuration.

AI Model Name

Model used for AI features.

The model list can be fetched from OpenAI after the API key is saved.

OpenAI Request Timeout (seconds)

Maximum time to wait for an OpenAI response.

Practical recommendation:

• 60 seconds for more stable production operation.

Enable AI Diagnostic Logging

Enables diagnostic logging of AI requests and responses.

Useful for:

• integration,
• testing,
• analyzing timeouts and response errors.

AI Diagnostic Max Chars

Maximum length of the logged preview payload.

Enable Affiliate Assistant

Enables the affiliate assistant if the store wants to use this feature.

Enable Weekly AI Reports

Allows generating recurring AI summaries.

Enable Product Knowledge Retrieval

Enables product knowledge retrieval from Vector Store.

Enable Program Knowledge Retrieval

Enables knowledge retrieval for affiliate program rules, FAQ, and documentation.

Product Vector Store Scope

Defines how product_vector_store_id is resolved.

Product Vector Store ID

Vector Store identifier if the store uses retrieval.

Redact Personal Data

Removes or masks personal data before sending prompts to the AI layer.

6.8. Reporting

Enable Reporting

Enables report generation and CSV exports.

Export Directory

Directory path where generated exports should be saved.

Example:

var/export/affiliate

7. Configuring a customer as an affiliate

After installation, the module extends Magento customer edit with affiliate fields.

In customer edit, you can manage:

• Affiliate Participant
• Affiliate Status
• Affiliate Referral Code
• Affiliate Website URL
• Affiliate Notes
• Affiliate Balance
• Affiliate Coupon Discount (%)

7.1. Affiliate Participant

Indicates whether the customer is part of the affiliate program.

7.2. Affiliate Status

Key statuses:

• Pending
• Active
• Suspended
• Rejected
• Blocked

7.3. Affiliate Balance

The balance is calculated automatically from approved and payout ready commissions.

The field:

• is visible in customer edit,
• should not be edited manually,
• updates automatically after commission changes.

7.4. Affiliate Coupon Discount (%)

This field assigns the affiliate a percentage discount that will work with their referral_code.

If you enter a value greater than 0, the module:

• creates or updates a Magento cart rule,
• sets the coupon equal to the affiliate code,
• allows customers to use the code as a cart coupon,
• attributes the order to the affiliate based on coupon_code.

Example:

• the affiliate code is FMX1FBXXY3
• the administrator enters 5
• the customer uses FMX1FBXXY3 as the coupon
• Magento applies a 5 percent discount
• the module attributes the order to the affiliate.

8. Module cron jobs

The module uses cron jobs in the default group.

8.1. Auto approve commissions

job: kowal_affiliate_auto_approve_commissionsschedule: */15 * * * *

The job:

• checks pending commissions,
• after the hold period changes them to approved.

8.2. Process notifications

job: kowal_affiliate_process_notificationsschedule: */10 * * * *

The job:

• processes the notification queue,
• marks entries as sent,
• for the email channel, sends transactional emails.

8.3. Cleanup notification log

job: kowal_affiliate_cleanup_notification_logschedule: 30 2 * * *

The job:

• removes old notification log entries according to retention.

8.4. Weekly AI insights

job: kowal_affiliate_generate_weekly_ai_insightsschedule: 0 6 * * 1

The job:

• generates weekly AI insights if enabled.

9. CLI commands

The module provides service commands:

bin/magento kowal:affiliate:auto-approvebin/magento kowal:affiliate:process-notificationsbin/magento kowal:affiliate:cleanup-notificationsbin/magento kowal:affiliate:generate-ai-insightsbin/magento kowal:affiliate:export-report

The most useful during initial launch are:

bin/magento kowal:affiliate:process-notificationsbin/magento kowal:affiliate:auto-approve

10. First test after installation

After configuration, a simple end to end test is recommended.

10.1. Affiliate registration test

1. Open the affiliate registration form.
2. Submit the application.
3. Verify the affiliate account was created.
4. Verify the customer has status Pending.
5. Verify notification entries were created.

10.2. Activation test

1. Open customer edit in the admin panel.
2. Set affiliate status to Active or use the approve action.
3. Verify the customer can see the affiliate dashboard.

10.3. Affiliate link test

1. Copy the affiliate link from the dashboard.
2. Enter the store through that link.
3. Add a product to cart.
4. Place an order.
5. Verify the order has:
   • affiliate_id
   • affiliate_referral_code
   • is_affiliate_order = 1

10.4. Affiliate coupon test

1. Set Affiliate Coupon Discount (%) for the affiliate, for example 5.
2. Save the customer.
3. Ensure the affiliate has status Active.
4. In the cart, enter their Referral Code as a coupon.
5. Place an order.
6. Verify:
   • the discount was applied,
   • the order was attributed to the affiliate,
   • a commission was created.

10.5. Payout test

1. Approve the commission or wait for auto approval.
2. Check the affiliate balance.
3. Submit a payout request.
4. Mark the payout as paid in the admin panel.

11. Most common issues after install

11.1. No commission after an order

Check:

• whether the order has affiliate_id,
• whether commissions are enabled,
• whether the module is running after the fix that creates commission after affiliate data is saved on the order,
• whether a record appears in kowal_affiliate_commission.

11.2. Customer grid does not show the current affiliate balance

Check:

• whether the customer_grid index was refreshed,
• whether reindexRow runs after saves,
• whether the value in customer edit matches the value in the grid.

If needed, run:

bin/magento indexer:reindex customer_grid

11.3. AI does not respond

Check:

• whether Enable AI is enabled,
• whether a valid OpenAI API Key was saved,
• whether the model was selected,
• whether the timeout is not too low,
• whether var/log shows OpenAI request errors.

11.4. Notifications are not sent

Check:

• whether Magento cron is running,
• whether Enable Notifications is enabled,
• whether entries are saved to kowal_affiliate_notification_log,
• whether you can run manually:

bin/magento kowal:affiliate:process-notifications

12. Recommended starter configuration

For a first production rollout, the following setup is recommended:

• Enable Module = Yes
• Enable Affiliate Registration = Yes
• Tracking Cookie Lifetime = 30
• Enable Commissions = Yes
• Default Commission Rate = 10
• Commission Hold Period = 14
• Enable Payouts = Yes
• Minimum Payout Amount = 100
• Enable Notifications = Yes
• Block Self Referral = Yes
• Enable AI = No as a starting point if the store does not need AI from day one

13. Summary

After proper installation and configuration, Kowal_Affiliate enables a complete partner program in Magento 2, including:

• affiliates,
• referral links,
• affiliate codes,
• affiliate discount coupons,
• commissions,
• payouts,
• notifications,
• partner dashboard,
• basic security and automation.