Referral Program

The referral program lets customers share a unique referral link and earn wallet credit when the people they invite make their first purchase. Merchants configure reward amounts, eligibility rules, and spending conditions from WooCommerce settings.

Overview

When the referral program is enabled, each customer receives a unique referral link tied to their account. They can share this link with friends, family, or followers. When a referred person registers and completes a qualifying purchase, both the referrer and the new customer can receive wallet credit, the amounts and conditions are fully configurable.

Referral rewards are credited to the wallet immediately after the qualifying order reaches the configured status (default: Processing). Credits appear in the wallet transaction ledger with a source type of referral_reward and are subject to the same spending limits and velocity caps as other wallet credit.

How It Works

1. Customer A has a WalletPro account. Their referral link is available in My Account > Wallet > Referral.
2. Customer A shares the link. The link contains a unique code (e.g., ?ref=abc123) that is stored in a cookie or session when a new visitor lands on the store.
3. The referred visitor registers a new account. The referral code is attached to the new user record at registration time.
4. The new customer completes their first qualifying order. WalletPro checks eligibility (minimum order total, new customer only, allowed payment methods).
5. Once the order reaches the configured trigger status, both rewards are issued:
   • Referrer reward, credit added to Customer A's wallet.
   • Referee reward, credit added to the new customer's wallet (if configured).
6. Both customers receive an email notification (if enabled) and can view the credit in their wallet dashboard.

Configuration

All referral program settings are found at WooCommerce > WalletPro > Referral Program.

General Settings

Eligibility Rules

Notifications

Setting Up the Referral Program (Merchant)

1. Go to WooCommerce > WalletPro > Referral Program.
2. Check Enable Referral Program.
3. Set Referrer Reward Amount to the credit you want to give the referring customer (e.g., 10.00).
4. Optionally set Referee Reward Amount if you want to also reward the new customer on their first order.
5. Choose a Reward Trigger Status. For physical goods, Processing is common. For digital goods or when you want to wait for fulfillment, choose Completed.
6. Set a Minimum Order Total if you want to prevent very small orders from triggering rewards.
7. Enable Exclude Wallet Payments if you do not want customers to refer friends and then have those friends pay with gifted wallet credit to generate more wallet credit.
8. Save changes.
9. Test the program by creating two test accounts, sharing a referral link between them, and placing a test order through WooCommerce's sandbox payment method.

Customer Experience

Finding the Referral Link

Logged-in customers access their referral link at My Account > Wallet > Referral. The tab shows:

• Their unique referral link (e.g., https://yourstore.com/?ref=abc123)
• A Copy Link button
• Share shortcuts (Email, if configured)
• A summary table: total referrals sent, conversions, and total credit earned from referrals

Sharing the Link

Customers can share the referral link via any channel, email, messaging apps, social media. The link works for any new visitor who has not previously registered on the store. When the visitor clicks the link, WalletPro sets a browser cookie with the referral code. The cookie persists for the number of days configured in Cookie Lifetime.

Registering and Converting

The referred visitor registers a new account and completes checkout. WalletPro reads the referral code from the cookie at registration and stores it on the user record. At checkout, the referral attribution is preserved even if the customer registered before starting the cart.

Receiving the Reward

Once the order reaches the trigger status, both rewards post automatically. The referring customer sees a new line in their wallet transaction history:

• Type: Referral Reward
• Description: Referral reward for [New Customer Name]'s first order #[order number]
• Amount: +$[referrer reward amount]

If notifications are enabled, both customers receive an email at this point.

Referral History (Admin)

Merchants can view referral activity at WooCommerce > WalletPro > Referral Program > Referral History. The table shows:

Click Export CSV to download the full referral history. The export respects any active date range filter.

Reward Reversal on Refund

If the qualifying order is fully refunded, WalletPro automatically reverses the referral rewards:

• The referrer's wallet is debited by the referrer reward amount.
• The referee's wallet is debited by the referee reward amount (if one was issued).
• Both reversals appear in the wallet ledger with type referral_reversal and reference the original order number.
• If the customer's wallet balance is insufficient to cover the reversal, the balance goes to zero (it does not go negative).

Analytics

Referral program metrics are included in the WalletPro Analytics dashboard at WooCommerce > WalletPro > Analytics, under the Referrals tab:

• Total referral conversions over the selected date range
• Total credit issued (referrer + referee combined)
• Conversion rate (referrals sent vs. accounts registered vs. orders placed)
• Top referrers ranked by conversion count and total credit earned
• Average order value of referred first orders vs. non-referred first orders

Developer Integration

Hooks

WalletPro exposes hooks to customize referral behavior without modifying plugin files.

Filter: walletpro_referral_reward_amount

Modify the referrer reward amount before it is credited. Runs after eligibility checks pass.

add_filter( 'walletpro_referral_reward_amount', function( $amount, $referrer_id, $order ) {
    // Double the reward for customers who have referred 5+ people before
    $previous = walletpro_get_referral_count( $referrer_id );
    if ( $previous >= 5 ) {
        return $amount * 2;
    }
    return $amount;
}, 10, 3 );

Filter: walletpro_referral_is_eligible

Return false to block a referral conversion from being processed.

add_filter( 'walletpro_referral_is_eligible', function( $eligible, $order, $referrer_id ) {
    // Only allow referrals for orders containing products from category ID 42
    $items = $order->get_items();
    foreach ( $items as $item ) {
        $product = $item->get_product();
        if ( has_term( 42, 'product_cat', $product->get_id() ) ) {
            return true;
        }
    }
    return false;
}, 10, 3 );

Action: walletpro_referral_reward_credited

Fires after a referral reward is successfully credited. Useful for logging or triggering external events.

add_action( 'walletpro_referral_reward_credited', function( $referrer_id, $referee_id, $order_id, $amount ) {
    // Send referrer a Slack notification or log to external analytics
    my_analytics_track( 'referral_converted', [
        'referrer' => $referrer_id,
        'referee'  => $referee_id,
        'order'    => $order_id,
        'amount'   => $amount,
    ] );
}, 10, 4 );

REST API

Referral data is accessible via the WalletPro REST API under the walletpro/v1 namespace.

GET /walletpro/v1/customers/{id}/referrals

Returns the referral history for a specific customer (as referrer).

# Requires: manage_woocommerce capability or the customer's own auth token
curl -X GET \
  https://yourstore.com/wp-json/walletpro/v1/customers/42/referrals \
  -H "Authorization: Bearer <token>"

Example response:

{
  "referrer_id": 42,
  "referral_link": "https://yourstore.com/?ref=abc123",
  "referral_code": "abc123",
  "stats": {
    "total_referrals": 7,
    "conversions": 3,
    "total_credit_earned": "30.00",
    "currency": "USD"
  },
  "referrals": [
    {
      "referee_id": 88,
      "referee_email": "jane@example.com",
      "order_id": 10045,
      "order_total": "75.00",
      "reward_amount": "10.00",
      "status": "awarded",
      "awarded_at": "2026-05-14T11:22:00Z"
    }
  ]
}

WP-CLI

Check or manually trigger referral processing from the command line:

# List all referral conversions in the last 30 days
wp wallet referrals list --days=30

# Show referral stats for a specific customer (by user ID)
wp wallet referrals stats --user=42

# Manually process referral reward for an order (if auto-processing was skipped)
wp wallet referrals process --order=10045

# Reverse referral rewards for a refunded order
wp wallet referrals reverse --order=10045