WordPress LongXiao Affiliate System — See Your Data at a Glance, Settle Commissions in One Click: Multi-Language E-Commerce Affiliate Backend

1. Background & Positioning

The LongXiao Affiliate plugin (LongXiao 加盟推广外挂) is a purpose-built WordPress affiliate program management system developed by Salong Network, designed exclusively for the LongXiao Theme. While mainstream WordPress affiliate plugins such as AffiliateWP and WooCommerce Affiliate offer robust general-purpose features, they fall short when integrated with the LongXiao Theme's unique architecture — a decoupled backend (WordPress + WPGraphQL) and frontend (Vue.js/Nuxt.js) stack, native multi-language and multi-currency support, a comprehensive balance and points system, and a real-time notification engine. The LongXiao Affiliate plugin bridges this gap entirely.

The plugin employs a pure custom database table architecture — no WordPress Custom Post Types (CPTs) are used. All affiliate profiles, referral records, visit logs, creative assets, and URL management data reside in dedicated, optimized database tables that interface seamlessly with the theme's GraphQL query layer. The WordPress admin panel provides a complete "Affiliate Program" top-level menu with eight sub-menu pages, covering the full operational lifecycle from affiliate onboarding and commission settlement to in-depth data reporting. Whether you run a vertical e-commerce store, a content monetization community, or a cross-border multilingual shop, this plugin delivers a precise, efficient, and customizable affiliate management experience.

2. Core Menu Features in Detail

2.1 Overview — Command Center Dashboard

The Overview page serves as the plugin's command center, displaying ten key metric cards for at-a-glance operational status: Total and Active Affiliates, Total Creatives, Total URLs, Total Referrals, Total Visits, Total Conversions, Conversion Rate, Total Commission, Total Paid Commission, and Total Unpaid Commission. These ten metrics give managers an immediate read on the health of the entire affiliate program.

Below the cards, four data tables are arranged in a 2x2 grid layout forming an operational watchtower:

• Top Earners: Ranked by total earnings and referral count, helping identify high-value affiliates at a glance.
• Recent Registrations: New affiliate sign-ups with their current approval status, enabling quick follow-up.
• Recent Visits: Incoming traffic from affiliate referral links, showing the source URL, campaign parameters, and referrer.
• Recent Referrals: Latest order conversion activity with status labels (paid, unpaid, rejected, refunded).

The dashboard is designed so that managers can complete daily inspections without navigating to multiple sub-pages, quickly spotting anomalies such as a surge in rejected applications or a sudden drop in visit volume.

2.2 Affiliates — Full Lifecycle Management

The Affiliates page is the operational hub. It uses the standard WordPress WP_List_Table to display all affiliate records, with columns for ID, User ID, Status, Commission Rate, Total Earnings, Unpaid Earnings, Referral Count, Visit Count, Registration Date, and Approval Date.

The table supports search by user ID, bulk deletion, and four predefined affiliate statuses:

• Pending: New applications awaiting manual review. The action column provides green "Activate" and red "Reject" buttons.
• Active: Affiliates currently promoting. Actions include Deactivate, Edit, and Delete.
• Inactive: Temporarily suspended affiliates that can be reactivated with one click.
• Rejected: Applications that did not pass review. Rejected affiliates can resubmit their application from the frontend — the status resets to "pending" and a new admin notification is triggered.

The Edit form allows modification of Status (dropdown), Commission Rate (percentage or flat amount), Commission Type, Website URL, Application Reason, Cumulative Earnings, Unpaid Earnings, Referral Count, Visit Count, and Registration Date. Every status change automatically triggers the LongXiao Theme's notification engine (supporting in-site, email, and WeChat channels — each independently togglable) and email templates, ensuring affiliates receive real-time updates on their application status in their user dashboard.

A summary stats bar is displayed above the table, showing "Current Page" and "Total" aggregates for visits, referrals, and conversions under the current filter criteria, along with locale-specific cumulative earnings and unpaid earnings (displayed in their respective currencies for multi-currency setups). This allows managers to grasp data distribution at a glance without manual summation.

2.3 Referrals — Order-Level Commission Ledger

The Referrals page manages every order conversion generated through affiliate links. The table displays: ID, Affiliate, Customer, Order ID, Amount, Status, Description, Date, and Locale (in multilingual setups).

Top filters allow quick searching by Order ID, Affiliate ID, Customer ID, and Status (All, Unpaid, Paid, Rejected, Refunded). Built-in bulk actions (Accept, Reject, Delete) greatly accelerate review workflows. The Visits, Creatives, and URLs pages also support bulk deletion. All list tables allow customizing the number of items displayed per page via Screen Options (default 20).

A summary stats bar is displayed above the table, showing "Current Page" and "Total" aggregations for paid and unpaid commission amounts. In multilingual environments, amounts are broken down by locale with their respective currency symbols, giving managers immediate visibility into total promotional costs.

The Add/Edit referral form includes all relevant fields: Affiliate User ID (required), Customer ID, Order ID (required), Amount (required), Locale (for multilingual sites), Visit ID, Status, Reference, Context, and Description. The plugin includes a concurrency lock mechanism (powered by WordPress Transient API) to prevent duplicate commission records for the same order. When a referral status changes to "Paid", the plugin automatically calls the LongXiao Theme's Balance library to credit the affiliate's account balance, sends an in-site notification, and dispatches email and WeChat notifications. When an order is refunded, the system automatically deducts the corresponding amount from the balance and deducts the corresponding affiliate referral points, creating a fully automated commission accounting loop.

2.4 Visits — Full-Funnel Traffic Attribution

The Visits page logs every visit that arrives via an affiliate referral link, with complete granular data. Columns include: ID, Affiliate, Visitor, Visit URL, Referrer, Campaign, Device Type (Desktop/Mobile/Tablet), Browser, OS, Converted (Yes/No), Date, and IP Address.

Each record captures detailed device fingerprint information — critical for fraud prevention. Combined with the plugin's anti-fraud settings, managers can easily identify high-frequency anomalous traffic originating from the same device or IP address.

The "Converted" flag bridges visit logs with referral records, allowing managers to trace every commission payment back to its originating channel, campaign, and creative asset. This enables precise ROI attribution analysis at the most granular level. The plugin includes a built-in system log table (salong_affiliate_logs) that automatically records commission skips, payout failures, and other exceptional events, providing a complete audit trail for troubleshooting.

2.5 Creatives — Standardized Promotional Asset Library

The Creatives page manages promotional materials provided to affiliates. Three asset types are supported: Image, QR Code, and Link. The table displays: ID, Type (with image thumbnail), Name, Campaign, URL, Status (Active/Inactive), Created At, and Updated At.

The plugin includes a built-in QR Code generator (powered by the api.qrserver.com external API) that can generate a QR code image from a URL and name with one click, automatically uploading it to the WordPress media library. The three asset types use JavaScript-driven dynamic field toggling in the edit form for a smooth user experience.

Each creative supports online/offline toggling, allowing managers to control asset availability in sync with marketing campaign rhythms. On the LongXiao Theme frontend, affiliates can only see assets with an "Active" status in their creative materials page, ensuring asset control and timeliness.

2.6 URLs — Affiliate Referral Link Dashboard

The URLs page displays all referral link records in the system: ID, User ID, URL, Campaign, Visit Count, Converted Count, Created At, and Updated At. This page corresponds to the links that affiliates create themselves on the LongXiao frontend — operations staff can centrally manage all manually created referral links and view real-time visit and conversion statistics for each link.

Both "Visit Count" and "Converted Count" are queried live from the visits table, giving managers immediate visibility into which links drive the best traffic and conversions. This data is invaluable for making informed campaign investment decisions.

2.7 Reports — Multi-Dimensional Business Analytics

The Reports module is the most sophisticated feature of the plugin. It uses a tabbed navigation interface with date range filtering and supports drill-down by Affiliate ID, Campaign, and Locale. Four tabs each focus on a different analytical dimension:

Affiliates Tab: Total affiliates all-time, new affiliates in the period, best-converting affiliate by conversion rate, and the conversion rate value. A daily trend chart visualizes new affiliate registrations, while a Top 10 conversion rate leaderboard helps managers quickly identify top performers.

Referrals Tab: Displays all-time paid amount, all-time unpaid amount, period paid/unpaid amounts and averages — all broken down by currency/locale for multi-currency setups. A daily trend chart visualizes the commission payout curve, a per-locale matrix provides cross-language comparisons, and Top 10 rankings for referral count and commission amount highlight top earners.

Visits Tab: Shows all-time total visits, period visits, period converted visits, all-time conversion rate, and best referrer source. A daily trend chart tracks visit and conversion volumes, while a source ranking table identifies the highest-performing traffic channels.

Campaigns Tab: Displays all-time distinct campaign count, best-converting campaign all-time, most active campaign in the period, and best-performing campaign by referrals in the period. Daily trend charts and Top 10 rankings for most active and best-converting campaigns provide campaign-level effectiveness comparisons.

All report charts are rendered using Chart.js v4.5.1, paired with the plugin's custom data cache versioning mechanism to ensure smooth loading even with large datasets.

2.8 Settings — Flexible and Configurable Business Rules

The Settings page, powered by the Codestar Framework, is organized into four configuration sections:

General Settings: Toggle open/closed self-registration, enable/disable self-referral, require manual approval, select the affiliate agreement page, set the referral URL query parameter (defaults to "ref"), configure application reason length (default 6-50 characters), and enable sensitive word filtering.

Commission Rules: Support percentage-based or flat-rate commission calculation. Each affiliate can have an individual rate that overrides the global default (new affiliates inherit the global configuration). Configurable fields include commission rate, flat rate amount, and cookie duration in days (default 30). Note: point-only payment orders are excluded from referral conversions.

Exclusion Rules: Seven rules provide comprehensive commission policy control: exclude unpaid orders, exclude free/zero-value orders, credit the last referrer only, exclude coupon amounts, exclude shipping fees, exclude specific products, and exclude point-only payment orders from commission calculation.

Anti-Fraud Settings: Global anti-fraud toggle, device fingerprint checking, device frequency limit, IP frequency limit, and time window configuration. This four-dimensional protection system effectively deters click fraud and protects the platform's commission expenditure.

3. Synergistic Advantages with the LongXiao Theme

The integration between the LongXiao Affiliate plugin and the LongXiao Theme goes far beyond simple "compatibility" — it is a deep, bidirectional, native fusion:

1. Full GraphQL Data Layer Integration: The plugin registers complete WPGraphQL query and mutation types. The LongXiao frontend retrieves all affiliate page data through a single salongGetAuthorContent GraphQL query, eliminating the need for custom REST API development.
2. Balance System Integration: Commission payouts don't require a separate withdrawal module. Earnings flow directly into the LongXiao Theme's Balance system and are managed alongside the platform's member balance.
3. Notification & Activity Feed Convergence: Affiliate application reviews, commission credits, and order refunds automatically trigger the LongXiao Theme's in-site notifications, email notifications, WeChat notifications (all three channels independently togglable), and activity feed. Affiliates receive all promotion-related messages in their user dashboard's Notifications and Activity channels.
4. Native Multi-Language & Multi-Currency Support: Through the LongXiao Theme's Polylang integration layer, every referral, creative asset, and URL record can be associated with a language locale. Reports support split statistics by currency, meeting the complex requirements of cross-border multilingual e-commerce.
5. Points System Interlock: When a referral converts successfully, the theme's Points system can automatically award affiliate referral points (default 100, configurable in the theme's points settings). When a refund occurs, the system deducts the corresponding points as well, creating a balanced dual-incentive mechanism of "commission + points".
6. Seamless Frontend Routing Embedding: The plugin does not need to create any frontend templates. The LongXiao Theme's native /user/{id}/affiliate/* route structure resolves plugin data directly, enabling affiliates to apply, view statistics, manage links, and handle creative materials entirely from within their user dashboard.

4. Practical Value & User Benefits

From an operational standpoint, the plugin addresses the three most critical challenges in e-commerce affiliate programs:

Operational Efficiency: From affiliate application review to commission settlement, every operation stays within the WordPress admin. List table bulk actions, search filtering, and rapid status toggling multiply daily operational efficiency.

Data-Driven Decision Making: The eight menu items cover the complete "acquisition → tracking → conversion → settlement → analysis" data chain. Managers never operate on gut feeling — every commission payout has a fully auditable visit → conversion → settlement trail.

Risk Mitigation: Anti-fraud settings, exclusion rules, and device fingerprint logging in visit records protect platform interests at both the rule level and the technical level, effectively reducing financial losses from click fraud.

5. Target Audience

The LongXiao Affiliate plugin is ideally suited for site managers building multilingual e-commerce platforms with the LongXiao Theme — including cross-border independent stores, vertical-niche e-commerce sites, and digital product marketplaces. It is especially valuable for operations teams that want to establish their own affiliate program, reduce customer acquisition costs, and implement granular promotion tracking. The plugin is equally well-suited for platform-type sites that need to provide standardized promotional tools and commission settlement mechanisms for content creators, KOLs, and community group leaders.