# PPL Affiliates for WooCommerce - User Guide This guide is for store owners and managers. It covers everything from first setup to paying affiliates, in plain language. No coding required. Developers should also see `developer-guide.md` for hooks and the REST API. ## Contents 1. What this plugin does 2. Quick start (the setup wizard) 3. The one page affiliate experience 4. Settings, tab by tab 5. Building your signup form 6. Approving and managing affiliates 7. Commissions and how they are calculated 8. Tiers (rewarding your best affiliates) 9. Creatives (banners and links for affiliates) 10. Paying affiliates (PayPal and bank transfer) 11. Emails 12. Reports and exports 13. Fraud protection 14. Multi level (recruiting) network 15. The affiliate dashboard 16. Shortcodes 17. Frequently asked questions 18. Troubleshooting --- ## 1. What this plugin does It turns your WooCommerce store into an affiliate program. Affiliates share a personal link. When someone clicks it and buys within the tracking window, the affiliate earns a commission. You review and pay those commissions. Everything lives under the **Affiliates** menu in wp-admin. --- ## 2. Quick start (the setup wizard) When you first activate the plugin it opens a short wizard. It asks three things: 1. **What affiliates earn** - a percentage of each order (for example 20%) or a fixed amount. You also set how long a referral link keeps working (the cookie window, default 30 days) and a holding period before commissions can be paid (default 14 days, which protects you from refunds). 2. **Who can join** - approve applications automatically, or review each one. You also set the minimum balance before someone is paid (default 100). 3. **Your affiliate page** - let the plugin create an "Affiliate Program" page for you. This single page shows the signup form to visitors and becomes the dashboard once someone is approved. You can re-run the wizard any time from **Affiliates > Tools**. --- ## 3. The one page affiliate experience There is a single shortcode, `[ppl_afw_portal]`, that does everything: - A logged out visitor sees a short pitch and a login or create-account button. - A logged in person who is not yet an affiliate sees the **signup form**. - Someone whose application is pending or declined sees a status message. - An approved affiliate sees their full **dashboard**. So you only need one page. The wizard creates it, or add the shortcode to any page yourself. --- ## 4. Settings, tab by tab Find these under **Affiliates > Settings**. There are two modes, set on the **Advanced** tab: - **Simple** (default) shows the everyday options and hides the Multi-level and Fraud tabs so the screen is not overwhelming. - **Advanced** shows every option. ### Commissions tab - **Default commission** - the percentage or fixed amount affiliates earn. Percentages are automatically capped at 100%. - **Exclude discounts / Include tax / Include shipping** - what counts toward the commission base. - **Minimum order amount** - orders below this earn nothing. - **Grace period** - how long commissions stay locked before they can be paid, so refunded orders are never paid out. - **Block self referrals** - stop affiliates earning on their own purchases. - (Advanced) exclude specific products, categories, or customer roles, only reward first-time customers, and set **purchase sequence rules** (for example 30% on a customer's first order, 10% on orders 2 to 5, 5% after that). ### Tracking tab - **Cookie duration** - the referral window in days. - **Attribution model** - last click or first click wins. - **Cookieless fallback** - still attribute when cookies are blocked. - **Clear cookie on purchase** - end the window once a commission is recorded. - **Coupon tracking** - assign a coupon to an affiliate so they earn whenever it is used, even without a link. - (Advanced) rename the URL parameter, change the pretty link base (`/go/slug/`), and enable direct link tracking from an affiliate's verified website domain. ### Affiliates tab - **Auto approve** - activate applications instantly. - **Registration form fields** - the drag and drop form builder (see section 5). - **Program terms** - text shown above the terms checkbox on the signup form. - **Lifetime commissions** - once an affiliate refers a customer, they earn on that customer's future orders too. - (Advanced) terms version, lifetime link expiry, and recurring commissions for WooCommerce Subscriptions renewals. ### Payouts tab See section 10. ### Portal tab - **Dashboard page ID** - the page with the `[ppl_afw_portal]` shortcode. Used in emails. - **Accent color** and **corner radius** - match the dashboard to your brand. - **Leaderboard** - show a friendly 30 day top earners board (names appear as initials only). ### Multi-level tab (advanced) See section 14. ### Fraud tab (advanced) See section 13. ### Advanced tab - **Settings mode** - simple or advanced. - **Delete data on uninstall** - off by default, so your data is safe unless you deliberately turn this on before deleting the plugin. --- ## 5. Building your signup form On **Affiliates > Settings > Affiliates**, the **Registration form fields** builder lets you decide exactly what to ask applicants. - Drag the handle to reorder fields. - Each field has a **label** (what the applicant sees), a **key** (where the answer is stored, filled in automatically from the label), a **type** (text, paragraph, website URL, email, phone, or number), and a **Required** toggle. - Click **Add field** to add more, or **Remove** to delete one. The default form asks for full name, website, main social profile, audience size, and how they will promote you. Website, email, and phone fields are checked for a valid format in the browser. Required fields must be filled in before the form can be submitted. --- ## 6. Approving and managing affiliates **Affiliates > All Affiliates** lists everyone with search, status filters (pending, active, suspended, rejected), and bulk actions. Select several rows and approve, reject, or suspend them at once. Click a name to open the **detail screen**, where you can: - Change status, referral slug, and a custom commission rate just for them. - Assign a tier or (with multi-level on) a parent affiliate. - Set their payout method and see their masked payout details. - Read their full activity log and recent referrals, visits, and payouts. - See their application answers. --- ## 7. Commissions and how they are calculated Every referred order creates a **referral** (a commission record). Its status moves through: - **Pending** - within the grace period, or waiting on order completion. - **Approved** - payable. The amount is added to the affiliate's unpaid balance. - **Paid** - included in a payout. - **Rejected / Refunded** - reversed (a refund automatically reverses or proportionally reduces the commission). The rate is chosen by a cascade, most specific first: a per affiliate per product rate, then a purchase sequence rule, then the affiliate's custom rate, then their tier, then a product rate, then a category rate, then your global default. You set product and category rates right on the WooCommerce product and category edit screens. **Affiliates > Referrals** lists them all with filters. You can approve or reject individually or in bulk, and add a **manual referral** to credit someone by hand. --- ## 8. Tiers (rewarding your best affiliates) **Affiliates > Tiers** lets you create commission tiers, for example Silver at 20% and Gold at 30%. Give each tier thresholds (a minimum number of approved referrals and minimum lifetime earnings). Each night the plugin promotes affiliates to the best tier they qualify for. It never demotes anyone. Tiers without thresholds are assigned by hand only. --- ## 9. Creatives (banners and links for affiliates) **Affiliates > Creatives** is a library of ready-made promotional material. - **Banner** - upload an image with the media picker. The image field only appears for banner creatives. - **Text link** - a piece of anchor text. - **Custom HTML** - your own markup; put `{{link}}` where the affiliate's referral URL should go. Affiliates see active creatives in their dashboard with a ready to paste embed code that already includes their referral link. The library tracks impressions and clicks so you can see what performs. --- ## 10. Paying affiliates (PayPal and bank transfer) ### Choosing methods On **Affiliates > Settings > Payouts**, tick the payout methods you offer: **PayPal**, **Bank transfer**, or both (store credit coupon is also available). Affiliates then pick one in their dashboard and enter their own details: - PayPal: their PayPal email. - Bank transfer: account holder name, account number or IBAN, routing / sort / SWIFT code, and bank name. All details are encrypted and only ever shown masked. ### The minimum **Minimum payout** (default 100) is the balance an affiliate must reach before they are paid. ### Running payouts Go to **Affiliates > Payouts**: - **Run payouts now** creates a payout for every affiliate above the minimum. - You actually send the money through PayPal or your bank. The plugin records the payout, assigns a sequential invoice number, and marks the balance paid. - **Export processing for PayPal (CSV)** downloads a file with each person's name, amount, and payout destination so you can pay them in one batch. - Each payout has a printable **invoice**. Failed payouts can be retried. You can also schedule payouts weekly, every two weeks, or monthly on the Payouts settings tab, or pay a single affiliate from their row on the Affiliates list. --- ## 11. Emails The plugin adds these to **WooCommerce > Settings > Emails**, where you can edit the subject, heading, and content, or switch any of them off: - **Affiliate approved** - to the affiliate. - **Affiliate rejected** - to the affiliate. - **New commission** - to the affiliate when they earn. - **Payout sent** - to the affiliate when you pay them. - **New affiliate application** - to you, the store admin. They use your normal WooCommerce email template, so they match your other store emails automatically. Affiliates can also turn off some notifications from their dashboard, and there is a separate in-dashboard notification feed. Send a one-off message to every affiliate from **Affiliates > Tools > Broadcast announcement**. --- ## 12. Reports and exports **Affiliates > Overview** shows headline numbers and a 30 day chart. **Affiliates > Reports** adds a date range, visit and commission charts, your top affiliates, and your top campaigns. Export affiliates or referrals to CSV from Reports or from **Affiliates > Tools**. --- ## 13. Fraud protection (advanced) When enabled, each referral is scored for risk signals: the affiliate buying through their own link, an order coming from an IP the affiliate has logged in from, or a flood of clicks in a short time. You set two thresholds: - **Hold** - referrals at or above this score are held until you release them. - **Suspend** - affiliates at or above this score are suspended automatically. **Affiliates > Fraud** lists every scored event. Release a held commission with one click. --- ## 14. Multi level (recruiting) network (advanced) Turn on **Multi level network** to let affiliates recruit other affiliates and earn a share of their recruits' commissions. Set how many levels deep and the rate per level (for example 10% from level one, 5% from level two). When it is on, an **Affiliates > Network** screen shows the recruitment tree, and affiliates get a Network tab in their dashboard. --- ## 15. The affiliate dashboard What your affiliates see on the `[ppl_afw_portal]` page once approved: - **Dashboard** - unpaid and lifetime earnings, visits, conversion rate, a 30 day earnings chart, achievement badges, an optional leaderboard, and recent commissions. - **Links & Creatives** - their referral links, a smart link builder that turns any store URL into a referral link, and the creatives library with copy buttons. - **Campaigns** - create named campaigns to see which promotions perform. - **Network** - their recruits (if multi-level is on). - **Payouts** - choose a payout method, enter their details, and see payout history. - **Settings** - change their referral slug and email notification preferences. - A **notification bell** with their in-dashboard feed. --- ## 16. Shortcodes - `[ppl_afw_portal]` - the complete experience: signup form, then dashboard. This is the only one most stores need. - `[ppl_afw_registration]` - just the signup form, for a standalone page. --- ## 17. Frequently asked questions **Do I need a separate signup page and dashboard page?** No. `[ppl_afw_portal]` is both. **How do affiliates get paid?** You send the money via PayPal or bank transfer using the details they entered, helped by the CSV export. The plugin records each payout and its invoice. **Are payout details safe?** Yes. They are encrypted and shown only masked. **Can I change what the emails say?** Yes, under WooCommerce > Settings > Emails. **Will uninstalling delete everything?** No, unless you first enable "Delete data on uninstall" on the Advanced tab. **Does it work with High Performance Order Storage and block checkout?** Yes to both. --- ## 18. Troubleshooting **The "Choose image" button on a creative does nothing.** Make sure you are on the creative editor screen (Add new or Edit a creative). The media library loads there. If your browser blocked scripts, reload. **Referral links are not tracking.** Check the cookie duration is not zero, that the affiliate is Active, and that you are testing from a different browser or an incognito window (self referrals may be blocked by your settings). **Commissions stay pending.** That is the grace period protecting against refunds. They approve automatically once the order is complete and the grace period passes, or you can approve them by hand on the Referrals screen. **An affiliate cannot be paid.** They may be below the minimum payout, or have not entered their PayPal or bank details yet.