Milestone Rewards

Milestone Rewards automatically credit wallet funds when a customer's cumulative spending reaches defined thresholds, incentivizing repeat purchases without requiring manual intervention from the merchant.

Overview

Milestone Rewards work by tracking each customer's lifetime (or period-based) paid order totals against a set of thresholds you define. When a customer's spend crosses a threshold, WalletPro credits a reward amount to their wallet and records the event in the audit ledger. Milestones can be configured as one-time achievements or as repeating tiers that reset after each unlock.

Because the reward is deposited directly into the customer's WalletPro wallet, redemption happens naturally at the next checkout, no coupon codes, no separate loyalty portal, and no manual processing.

How It Works

1. You define one or more milestone tiers, each with a spend threshold (e.g., $250) and a reward amount (e.g., $15 wallet credit).
2. After each order transitions to a qualifying status (default: Completed), WalletPro recalculates the customer's cumulative qualifying spend.
3. If the new total meets or exceeds a threshold that has not yet been awarded, the reward is credited to the customer's wallet immediately.
4. The customer receives an on-screen notice and an optional email notification.
5. The credit appears in the customer's wallet transaction history with the note "Milestone Reward, [Milestone Name]".
6. If a milestone is configured as repeating, the spend counter resets to zero after the reward is issued, and the customer can earn the same milestone again.

Qualifying Spend Calculation

By default, WalletPro counts the order subtotal (excluding shipping and tax) of orders in Completed status. You can change which order statuses count and whether shipping or tax is included in the Settings panel described below.

Orders paid entirely with wallet funds are excluded from milestone spend accumulation by default (configurable). This prevents circular reward loops where milestone credits generate more milestone credits.

Configuration

Navigate to WooCommerce > WalletPro > Milestone Rewards to manage all milestone settings.

Global Settings

Advanced Settings

Creating and Managing Milestones

Adding a New Milestone

1. Go to WooCommerce > WalletPro > Milestone Rewards.
2. Click Add Milestone.
3. Fill in the following fields:
   • Milestone Name, Internal label and the name shown to customers (e.g., Silver Spender). Keep it short and meaningful.
   • Spend Threshold, Cumulative spend amount required to unlock this milestone (e.g., 250.00).
   • Reward Amount, Wallet credit issued when the threshold is reached (e.g., 15.00).
   • Repeating, If checked, the spend counter resets to zero after reward issuance and the milestone can be earned again.
   • Status, Active or Inactive. Inactive milestones are skipped during processing.
4. Click Save Milestone.

Milestone Tier Example

A typical tiered program might look like this:

With this configuration, a customer spending $520 total would receive three credits ($5, $15, $35) for the first three milestones. All four milestones are evaluated on each qualifying order status change, so if a single large order crosses multiple thresholds, all applicable rewards are issued.

Editing or Deactivating a Milestone

1. Go to WooCommerce > WalletPro > Milestone Rewards.
2. Click the milestone name in the list to open its edit screen.
3. Change the Status field to Inactive to stop future awards without deleting the milestone's history.
4. Click Save Milestone.

Customers who already qualified before deactivation retain their awarded credits. Historical award records remain in the audit ledger.

Customer Experience

Milestone Progress in My Account

When Show Progress Bar in My Account is enabled, customers see a progress section on their Wallet dashboard at My Account > Wallet. The section shows:

• The name of the next milestone they have not yet earned.
• Their current qualifying spend toward that milestone.
• A visual progress bar indicating percentage completion.
• The reward amount they will receive upon reaching it.

Milestones already earned are listed below the active progress bar with the date awarded and the amount credited.

Reward Notification

When a milestone is reached, the customer sees a notice on the next page load (typically the order confirmation page or their account page): "Congratulations! You've reached the [Milestone Name] milestone. $X.XX has been added to your wallet."

If email notification is enabled, the customer also receives the Milestone Reward Earned transactional email containing the milestone name, reward amount, current wallet balance, and a link to their wallet dashboard.

Finding Milestone Credits in Transaction History

1. Customer goes to My Account > Wallet.
2. Scrolls to the Transaction History table.
3. Milestone credits appear with the type label Milestone Reward and a note showing the milestone name.
4. The customer can filter by transaction type or date using the table controls.
5. Transaction history is printable from the Print Statement button on the same page.

Developer Integration

Hooks

WalletPro fires the following hooks during milestone processing:

/**
 * Fired just before a milestone reward is credited.
 * Return false to prevent the award.
 *
 * @param bool   $should_award  True by default.
 * @param int    $customer_id   WP user ID.
 * @param array  $milestone     Milestone config array.
 * @param float  $current_spend Customer's current qualifying spend.
 */
apply_filters( 'walletpro_milestone_should_award', bool $should_award, int $customer_id, array $milestone, float $current_spend );

/**
 * Fired after a milestone reward has been successfully credited.
 *
 * @param int   $customer_id   WP user ID.
 * @param array $milestone     Milestone config array.
 * @param float $reward_amount Amount credited to the wallet.
 * @param int   $transaction_id WalletPro transaction ID.
 */
do_action( 'walletpro_milestone_awarded', int $customer_id, array $milestone, float $reward_amount, int $transaction_id );

/**
 * Fired after cumulative spend is recalculated for a customer.
 *
 * @param float $spend       Calculated spend total.
 * @param int   $customer_id WP user ID.
 * @param int   $order_id    The order that triggered recalculation.
 */
do_action( 'walletpro_milestone_spend_recalculated', float $spend, int $customer_id, int $order_id );

Blocking a Milestone Award Conditionally

Use walletpro_milestone_should_award to prevent a specific milestone from being issued under custom business logic:

add_filter( 'walletpro_milestone_should_award', function( $should_award, $customer_id, $milestone, $current_spend ) {
    // Block the 'Silver Spender' milestone for wholesale role customers.
    if ( 'silver-spender' === $milestone['slug'] && in_array( 'wholesale_customer', wp_get_current_user()->roles, true ) ) {
        return false;
    }
    return $should_award;
}, 10, 4 );

REST API, Milestone Endpoints

Base path: /wp-json/walletpro/v1

List Milestones

GET /wp-json/walletpro/v1/milestones

Returns all configured milestones. Requires manage_woocommerce capability.

Response example:

{
  "milestones": [
    {
      "id": 3,
      "name": "Silver Spender",
      "slug": "silver-spender",
      "threshold": "250.00",
      "reward_amount": "15.00",
      "repeating": false,
      "status": "active"
    }
  ]
}

Get Customer Milestone Progress

GET /wp-json/walletpro/v1/customers/{customer_id}/milestone-progress

Returns the customer's current spend, milestones earned, and progress toward the next milestone. Requires manage_woocommerce or the authenticated customer accessing their own record.

Response example:

{
  "customer_id": 42,
  "qualifying_spend": "312.50",
  "next_milestone": {
    "id": 4,
    "name": "Gold Spender",
    "threshold": "500.00",
    "reward_amount": "35.00",
    "remaining": "187.50",
    "progress_pct": 62.5
  },
  "milestones_earned": [
    {
      "milestone_id": 2,
      "name": "First Steps",
      "awarded_at": "2026-03-15T10:22:00Z",
      "reward_amount": "5.00",
      "transaction_id": 881
    },
    {
      "milestone_id": 3,
      "name": "Silver Spender",
      "awarded_at": "2026-05-02T14:08:00Z",
      "reward_amount": "15.00",
      "transaction_id": 1042
    }
  ]
}

Manually Award a Milestone

POST /wp-json/walletpro/v1/customers/{customer_id}/milestone-progress/award

Requires manage_woocommerce. Forces award of a specific milestone regardless of spend level. Useful for correcting missed awards after configuration changes.

WP-CLI

Recalculate milestone progress for a specific customer:

wp wallet milestone recalculate --user=42

Recalculate for all customers (runs as a background batch, outputs progress to stdout):

wp wallet milestone recalculate --all

List all configured milestones:

wp wallet milestone list

Force-award a specific milestone to a user:

wp wallet milestone award --user=42 --milestone=3 --note="Manually corrected after config change"

Reporting

Milestone award activity appears in two places in the admin:

• WooCommerce > WalletPro > Audit Ledger, Every milestone credit is a ledger entry with type milestone_reward, the customer ID, milestone name, amount, order reference, and a timestamp. The ledger is HMAC-chained and tamper-evident.
• WooCommerce > WalletPro > Program Analytics, The ROI/cohort dashboard includes a Milestone Rewards section showing total credits issued, number of unique customers reached, milestone conversion rates by tier, and average order value before and after first milestone award.

To export milestone transaction data, go to WooCommerce > WalletPro > Audit Ledger, filter by Transaction Type: Milestone Reward, and click Export CSV. The export is GL-friendly and includes all fields required for standard breakage and liability reporting.