USER GUIDE

Configure accurate WooCommerce affiliate tracking, branded links, commission rules, multi-tier rewards, payment-secured eligibility, and partial or automated payouts.

This guide follows the complete program workflow: establish policy, create attribution, secure customer payment, review earnings, and pay affiliates. Screenshots use an isolated demo store with fictional affiliates, orders, and transfers.

Settings are grouped by ownership. Global policy lives under Settings, partner-specific terms live in Program profiles, link records live in Referral links, and financial transfers live in Payouts.

PV Affiliate Manager adds a complete affiliate program to a WooCommerce store. Install the ZIP from Plugins → Add New → Upload Plugin, activate it, and confirm that WooCommerce is active. A new Affiliates menu appears in WordPress.

The plugin works with both WooCommerce High-Performance Order Storage and legacy order storage. Its screens use WooCommerce order objects, so displayed order numbers remain compatible with sequential and custom order-number plugins while the internal order ID remains the financial identity.

Admin navigation

• Dashboard: performance totals and recent commission activity.
• Affiliates: affiliate accounts and core status.
• Referral links: query and branded links.
• Program profiles: applications, recruiting relationships, overrides, and payout recipients.
• Activity, Marketing, Reports, and Payouts: operational records.
• Settings: global program policy.
• License & updates: license activation and update access.

Open Affiliates → License & updates. Paste the license from your Plugins Vault account or purchase confirmation, then choose Activate License. A valid license enables automatic WordPress updates. Affiliate tracking, reporting, and payout records remain accessible if the license is inactive.

The license screen is separate from program settings so the key is easy to find and does not become mixed with commission or provider credentials. Use Check status after moving domains or restoring a backup. Deactivate the key before permanently moving the license to another site.

Open Settings → Commissions. The commission basis determines which product value is multiplied by the percentage rate.

• Net after coupons: product revenue after discounts. Enable gateway-fee deduction if commissions should also exclude the detected transaction fee.
• Order prices before coupons: the product prices stored on the order before coupons, excluding tax and shipping. This uses the actual order price, including a sale price, rather than the product’s current regular price.
• Legacy policy: preserves the earlier coupon and fee behavior for existing installations.

Example: products total 100 before coupons, a coupon removes 20, and the gateway fee is 3. At 10%, advertised commission is 10. Net commission is 8 without fee deduction and 7.70 with fee deduction. Shipping, tax, and fee line items are not commissionable product value.

Calculation terms and the applicable base-currency exchange rate are frozen on the order when the commission is first processed. Changing a setting affects new calculations and does not silently rewrite historical terms.

The global commission type can be Percentage, Fixed per order, or Fixed plus percentage. Percentage applies to the eligible product basis. Fixed applies once per eligible order. Combined adds both.

Partial refunds reduce product-based commission and scale the fixed portion proportionally. A shipping-only refund does not reduce product commission. An order with no retained paid product value earns no commission, including the fixed component.

Use Program profiles when one affiliate needs a different type, percentage, or fixed amount. Affiliate overrides replace the global terms for that affiliate. Use Commission rules for product, variation, category, affiliate, or first-order policies. Avoid recreating the same exception in both places: affiliate overrides describe a partner’s commercial agreement; rules describe order-line conditions.

Open Settings → Commission rules. Create rules for an affiliate, product or variation, product category, and a customer’s first paid order. All conditions inside one rule must match. The first matching rule wins for each order line, using priority first and rule ID second.

A rule can replace the percentage or exclude the matching line. Excluded lines also remove their proportional share of a fixed commission. Use the order preview before saving to confirm which rule would match each line.

Rule matches and line rates are saved with the commission. Editing priorities later affects future orders only. This protects payout calculations from changing after a promotion ends.

In Settings → Commissions, enable Multi-tier commissions and enter tier percentages from the nearest recruiting affiliate outward. Up to ten levels are supported, and the combined percentages cannot exceed 100% of the direct affiliate’s commission.

Example: the direct affiliate earns 10. With tier rates of 10,5, the nearest parent earns 1 and the next parent earns 0.50. Tier amounts are additional rewards calculated from the direct commission, not additional percentages of the order value.

Assign the parent in Program profiles → Recruiting affiliate ID. The plugin rejects recruitment cycles. The ancestry chain and tier rates are frozen for each order, so changing a parent later does not redirect an existing earning. Refunds reduce direct and tier commissions together while preserving amounts already paid.

The standard query link remains available, for example ?ref=alex. In Settings → Tracking, choose the query parameter, cookie duration, numeric identifier behavior, attribution ownership, and allowed branded prefixes.

Branded links use /prefix/identifier. With the default prefixes, examples include /go/demo-workbook and /refer/alex/product/example/. Each saved link selects an affiliate, prefix, unique identifier, same-site destination, and behavior.

• 302 redirect: changes the browser address to the destination. Use this for checkout, account forms, and destinations that perform their own redirects.
• Direct: renders the destination while keeping the branded address. Use this for normal GET or HEAD landing pages.

Extra path segments and query parameters are forwarded. Incoming query values override matching destination values. Affiliate parameters are stripped so a visitor cannot reassign the link’s owner.

Prefixes must start with a letter, contain valid route characters, and avoid WordPress, post-type, or taxonomy routes. Identifiers accept lowercase letters, numbers, and hyphens. The prefix and identifier pair must be unique across every affiliate.

Destinations must stay on the current site. Embedded credentials, dot segments, encoded path separators, external domains, and referral-to-referral destinations are rejected with a specific explanation. A configured prefix cannot be removed while a saved link still uses it.

Exclude active branded-prefix paths from full-page and CDN caching. The plugin sends no-cache headers and includes an AJAX tracking fallback, but it cannot change an external cache or web-server rule. After adding a prefix, save WordPress permalinks if the server has not refreshed rewrite rules automatically, then test both the destination and recorded click.

Tracking can use the first valid referral or the last valid referral within the signed cookie lifetime. At checkout, the cookie and WooCommerce session are revalidated against an active affiliate. Self-referrals are blocked for matching logged-in users and billing email addresses.

Enable coupon attribution to assign an affiliate owner in the WooCommerce coupon editor. Choose whether the affiliate coupon or referral link has precedence. If the cart contains coupons owned by different affiliates, the plugin refuses attribution instead of guessing.

Lifetime ownership is optional. After a registered customer completes a payment-secured order, the winning affiliate can become the permanent owner for future eligible orders. The first secured ownership wins. Guest orders do not create permanent customer ownership.

In Settings → Affiliate program, enable applications, add a published terms URL and version, and choose manual review or automatic approval. Applicants must be logged in, provide a website and meaningful promotion plan, and accept the current terms.

The application appears in WooCommerce My Account. You can also place [pvam_affiliate_application] on a protected page. Review applications in Program profiles, where status can be Pending, Active, Rejected, or Suspended.

Only active affiliates can receive new attribution. Suspending an affiliate blocks new credit without deleting the historical financial record. Application and decision emails are controlled in Settings → Notifications.

A commission follows Pending → Pending withholding → Unpaid → Paid. “Unpaid” means the customer payment is secured and the affiliate is eligible to be paid. It does not mean the customer order is unpaid.

• Online gateways: the order must be Processing or Completed and WooCommerce must have recorded a valid payment_complete() event.
• Offline gateways: bank transfer, cheque, and cash on delivery must reach Completed. Add other offline gateway IDs in Payout policy.
• Other statuses: commissions remain Pending. Fully refunded orders become Rejected.

A paid date or transaction ID alone is not proof of capture. If a historical online order is verified outside the plugin, use the order action Affiliate: confirm payment received (after verification). This records evidence; it does not charge the customer or transfer money.

Set withholding days in Settings → Payout policy. After customer payment is secured, the commission remains booked during that period. With zero days it becomes Unpaid immediately. Repeated callbacks do not restart the clock.

A partial refund recalculates the retained product basis and reduces direct and tier commission. A full refund rejects the commission. Payments already sent to an affiliate are never erased. If a later refund makes the affiliate overpaid, the balance becomes negative and future eligible earnings offset that debt.

Manual commission adjustments remain attached to the order and scale with later refunds. The Activity screen records adjustment, profile, allocation, and provider outcome events for operational review.

Dashboard, Reports, Payouts, affiliate My Account, and CSV exports display the number returned by WooCommerce get_order_number(). This supports sequential and branded order-number plugins. The internal order ID remains the commission identity, so changing display format cannot create a second commission.

CSV files include separate Order Number and Internal Order ID columns. Formula-like order numbers are escaped. Import the Order Number column as text to preserve leading zeros.

The cleanup tool accepts one exact displayed order number per line by default. Missing or duplicate references stop resolution before deletion. Select Internal order IDs only for diagnostics or deleted orders. Paid allocations and pending withdrawal reservations are protected from cleanup.

Open Payouts and choose one affiliate from the searchable dropdown. Type at least three characters to filter by name, email, or affiliate ID, or choose directly from the list.

Eligible balance is commission available under the program rules. Available for a new payout subtracts funds reserved by pending withdrawals. The payment history table lists withdrawals and transfers, not individual commission rows; commission details remain in Reports and the Dashboard.

After sending money outside WordPress, enter a method or transfer reference and record the payment. Leave Amount blank to settle the full available balance or enter a positive amount with no more than two decimal places for a partial payout. Allocations are applied to the oldest eligible commission first.

In Settings → Payment providers, choose Manual, PayPal Payouts, or Stripe Connect as the global provider. Configure sandbox and live credentials separately. Sandbox is the default and test jobs never settle real affiliate earnings.

In each Program profile, either inherit the global provider or override it for that affiliate. Add the required PayPal recipient or Stripe connected account. A queued job freezes the provider, environment, recipient, currency, amount, and commission allocations so a later settings change cannot redirect it.

Stripe transfers funds to the connected account balance; it is not a bank-payout scheduler. Provider onboarding, available platform balance, API permissions, and account capability remain the administrator’s responsibility.

Provider jobs can be Prepared, Processing, Unknown, Succeeded, Completed, Test complete, or Failed. An Unknown result means the network outcome could not be proven. Check the original provider reference before retrying; never create a blind second transfer. A Prepared job that has not been dispatched can be cancelled safely.

Enable monthly payouts in Settings → Payout policy, select a day from 1 to 28, and set minimum and maximum withdrawal amounts. Each eligible affiliate is considered once per month. Manual-provider profiles are skipped, and funds already reserved by withdrawals are not added again.

WordPress cron must run reliably for scheduled payouts, notifications, retention, Brevo sync, and webhook retries. Review jobs and provider balances before enabling live dispatch.

Active affiliates use the WooCommerce My Account Affiliate area to view balances, commissions, branded links, campaigns, creatives, and withdrawals. The shortcode [pvam_affiliate_dashboard] renders the same dashboard on a protected page.

Affiliates can create their own branded links using only administrator-approved prefixes and valid same-site destinations. Duplicate or invalid values show a specific correction message. Affiliates may request a partial or full withdrawal within the configured minimum and maximum. A request reserves the amount until it is paid or cancelled.

Keep the dashboard behind login. Test the account as an affiliate role before launch to confirm the theme, account navigation, and cache exclusions.

Use Marketing to create same-site campaign destinations and Media Library creative assets. Published resources appear in affiliate My Account. Campaign IDs remain reserved after a campaign is unpublished so historical tracking stays unambiguous.

Enable Brevo in Settings → Integrations to sync approved affiliates who explicitly opt in. Use the shared PV Brevo Integration key or a dedicated key and list ID. Opting out removes the affiliate from the dedicated list; it does not create a global Brevo blacklist.

Audit webhooks require HTTPS and a signing secret. Payloads are HMAC signed, use event IDs for deduplication, and retry failed deliveries. The read-only commissions endpoint is available at /wp-json/pvam/v1/commissions to users with the required permission.

In Settings → Privacy, decide whether tracking requires consent, whether IP and browser details are stored, and how long visit records are retained. IP and browser collection are off by default. WordPress privacy export and erasure tools include affiliate data while retaining financial records required for accounting.

Before launch

1. Activate the license and verify updates.
2. Choose the commission basis, rate, withholding, currency, and refund policy.
3. Test one online paid order, one offline completed order, and one unpaid order.
4. Test query and branded links in a private browser and confirm the click and attribution.
5. Review multi-tier parents and ensure there are no cycles.
6. Keep providers in sandbox until recipients, balances, permissions, and recovery steps are verified.
7. Confirm cron, cache exclusions, notification sender details, privacy text, and terms version.
8. Export a report and verify displayed and internal order identifiers.

Use Tools carefully for historical adoption, cleanup, or recalculation. Existing paid allocations and reservations are guarded, and legacy records without frozen snapshots require review before adopting current terms.