Affiliate Pro for WooCommerce

An affiliate program for WooCommerce with a Persian dashboard, per-affiliate referral links, per-category commission rates, integer money math, and manual payout management — built for Iranian stores that want to grow through affiliates without spreadsheets and direct messages.

🇮🇷 توضیحات فارسی · Security · Changelog

What problem this solves

Many WooCommerce stores run affiliate programs with a spreadsheet and direct messages: codes are created by hand, commissions are recalculated manually, and payout history lives in a separate file. That stops scaling once there are more than a handful of affiliates, and a one-rial discrepancy is enough to lose trust.

This plugin keeps attribution, calculation, lifecycle state, and payout requests inside WooCommerce. Money is calculated in integer minor units so floating-point drift cannot accumulate across thousands of orders. Commission records are never deleted; they change state, so the financial history stays auditable.

Features

Attribution and tracking

• Per-affiliate link with ?ref=CODE and an 8-character code from the restricted [A-Z0-9] alphabet.
• Referral cookie for 1–365 days (default 30), HttpOnly, SameSite=Lax, and Secure on HTTPS.
• Last click wins; an invalid code never replaces an existing valid one.
• Attribution is written to the order when the order is created, not when it completes, so delayed payments, bank transfers, and manual approval do not lose the referrer.
• At most one click is recorded per visitor every 60 seconds: refreshes do not inflate the stats, while two different visitors clicking at the same time are both counted (the lock key is affiliate id + a hash of IP and User-Agent).
• Self-referral protection by WordPress user ID and billing email.

Commission calculation

• Percentage rate per affiliate plus per-category overrides.
• Product and category exclusions.
• Per-order commission cap, stored as an explicit negative adjustment line so the sum of the breakdown always equals the final amount.
• Base is the line total after discount; tax and shipping are opt-in.
• Integer minor-unit arithmetic and half-up rounding; no float on the money path.
• Currencies with 0–4 decimal places, driven by wc_get_price_decimals().

Commission lifecycle

• pending when the order is created.
• approved when the order reaches completed or processing (configurable).
• paid after the payout is settled.
• reversed on cancellation or full refund; the record is kept.
• rejected for manual rejection by an administrator.
• Allowed transitions are enforced in the domain layer; jumping from pending to paid is rejected.

Affiliate dashboard

• [wap_dashboard]: available balance, total approved commission, clicks in the last 30 days, and total clicks.
• Referral link with a copy button and select-on-focus behavior.
• Commission and payout tables that turn into label/value cards below 760 px.
• Payout request form with server-side validation and per-field error messages.
• [wap_join]: registration form that preserves submitted values after an error.

Administration

• Affiliate list with status filters, counts, and pagination.
• Commission list with status filters, totals, and HPOS-safe order links.
• Payout list with payout destination, reference number input, and status transitions.
• Settings for rates, exclusions, caps, minimum payout, and uninstall data deletion.
• POST-Redirect-GET after every mutation, so refreshing the page cannot repeat a payout.

Infrastructure

• HPOS (WooCommerce custom order tables) compatibility declared; all order access goes through the public order API.
• Block checkout (Store API) is supported alongside the classic checkout; attribution is written on the order in both flows.
• REST API for mobile apps and external panels.
• WP-Cron job that prunes old clicks and recovers missed commission approvals.
• A bespoke design system (CSS tokens, glass surfaces, one gold accent, dark mode via prefers-color-scheme) with Vazirmatn bundled in the plugin — no Google Fonts or CDN request at all.
• No runtime dependencies beyond PHP and WooCommerce, no build step, and no CDN JavaScript.

Requirements

The plugin header claims compatibility with WooCommerce up to 9.4. That claim has not been verified on a live WordPress/WooCommerce installation; only public API contracts were reviewed. Run a test order on staging before production use.

Installation and setup

Install from source

git clone https://github.com/sirdadfar/woo-affiliate-pro.git
cd woo-affiliate-pro
composer install --no-dev

Place the directory at wp-content/plugins/woo-affiliate-pro and activate it in WordPress. When installed as a zip without Composer, the plugin falls back to a bundled lightweight autoloader and still works.

First run

1. Activate WooCommerce. Without it, the plugin shows an admin notice and does nothing.

2. Create two pages.

   Page	Shortcode	Purpose
   Affiliate dashboard	[wap_dashboard]	Affiliate panel
   Affiliate signup	[wap_join]	Registration form

3. Open “Affiliate → Settings” and set the default rate, minimum payout, and other options.

4. Create a test account, register through [wap_join], and open the referral link in a separate browser or private window.

5. Place a test order and follow the commission through “Affiliate → Commissions”.

The installer creates these tables using the WordPress table prefix:

Configuration

Settings are stored in a single WordPress option named wap_settings. Monetary values (min_payout, max_commission) are stored in the smallest currency unit; for IRR without decimals, 100000 means 100,000 rials.

Extensibility filter

Usage

Affiliate journey

1. The customer signs in to a WordPress account.
2. On the [wap_join] page they enter a name, a mobile number matching 09xxxxxxxxx, and a payout method.
3. With auto-approval enabled the account becomes active immediately; otherwise it stays pending until an administrator approves it.
4. [wap_dashboard] shows the referral link, click stats, balance, and history.
5. Once the balance reaches the minimum payout, the payout form becomes available.
6. The request appears in the admin payout list, and its status is reflected back in the affiliate panel.

Administrator journey

1. Affiliates: approve, activate, disable, or reject a request.
2. Commissions: review base and status; approve manually or reverse.
3. Payouts: check the stored destination against the affiliate record, record a reference number, and move the request to processing, paid, or rejected.
4. Settings: change rates and rules. Changes affect future commissions and do not rewrite history.

REST API

Authentication uses WordPress cookie plus nonce, or an Application Password. The write route has its own rate limit and concurrency lock.

Security

• Every PHP file starts with defined( 'ABSPATH' ) || exit;.
• Every query with variables uses $wpdb->prepare(), and table names come from $wpdb->prefix.
• Every output is escaped with esc_html, esc_attr, esc_url, esc_textarea, or wp_kses_post.
• Every state-changing admin action checks both current_user_can and its own nonce; a failed nonce returns 403.
• Every REST route has a real permission_callback; no write route is public.
• Referral codes are strictly validated; `