Leaderboard for WooCommerce plugin

1. Introduction

This powerful tool allows you to create a dynamic leaderboard for your customers based on their WooCommerce purchases. Encourage competition, reward top customers with visual medals and prizes, increasing engagement and loyalty.

With this plugin you can:

• Display a list of top monthly buyers based on monthly amount or number of orders
• Automatically assign gold, silver and bronze medals.
• Assign real products as prizes for winners.
• Send notifications to winners.
• CSV file with leaderboard generation

This documentation will help you quickly install, configure and use all the plugin’s features.

2. Key Features

• Dynamic Leaderboard: Display a list of your customers in real time based on customized criteria.
• Medal System: Automatically award gold, silver, and bronze medals to top-ranking customers.
• Shortcode Support: Display the leaderboard anywhere on your site with a simple shortcode.
• Convenient settings interface: A simple interface for configuring all plugin options.
• Prize management: Ability to configure and assign monthly prizes (products from your store) for the top 3 positions directly from the plugin’s admin menu.
• Monthly purchase calculation: Accurate calculation of the monthly purchase amount of each user, taking into account only “completed” orders for fair ranking.
• Registered users only: Ensuring fairness and accuracy of data by including only registered users in the leaderboard competition.
• Detailed user information (for administrators/registered users): Administrators can view user details (full name, email, phone, and position) within the leaderboard interface. Logged-in users can view their own ranking and details in the leaderboard table.
• CSV file with leaderboard generation

Plugin’s screenshots

3. Installation and Activation

1. Download the plugin: Plugin ZIP archive.
2. Log in to WordPress: Go to the admin panel of your WordPress site.
3. Go to plugins: In the side menu, go to “Plugins” > “Add New”.
4. Download the plugin: Click the “Download Plugin” button at the top of the page.
5. Select File: Click “Choose File” and select the downloaded ZIP archive (leaderboard-for-woocommerce.zip).
6. Install: Click the “Install Now” button.
7. Activate: After successful installation, click the “Activate Plugin” button.
8. Go to Settings: Now you can find the plugin settings in the “WooCommerce” menu > “Settings” > “Leaderboard” tab.

4. Plugin Settings

All plugin settings are available in the WordPress admin panel: WooCommerce > Settings > Leaderboard.

4.1. General Settings

[Fill in this section with details about general settings. For example:]

• Shoppers per Page: Set the maximum number of buyers that will be shown on the leaderboard per page.
• Hide Month/Year Controls: Check this box to hide the month and year selection dropdowns by default. This can be overridden by the “hide_controls” attribute in the shortcode.
• Hide Prize Table: Check this box to hide the monthly prizes table by default. This can be overridden by the “hide_prizes” attribute in the shortcode.
• Leaderboard Theme: Choose the visual theme for the leaderboard table.

4.2. Prize Settings (Monthly Prizes)

This section allows you to assign specific WooCommerce products as prizes for winners. Prizes are assigned monthly.

• Find Monthly Prizes in WordPress admin menu in WooCommerce section.
• Click “Add New Monthly Prize” button.
• Set title for a month you need i.e. March 2025. Choose month and year in dropdowns correspondingly (March, 2025).
• Choose products for 1st-3rd place as prizes. You can choose any number of them (PRO version).

P.S.You can choose only one prize for each place in free plugin version

5. Using Shortcodes

The plugin provides a convenient shortcode to display the leaderboard on any page or post.

5.1. Shortcode [leaderboard_monthly]

This shortcode displays the main leaderboard. It has several attributes to customize the display.

Available attributes:

Basic usage:

[leaderboard_monthly]

Displays the leaderboard for the current month with default settings.

Extended usage:

[leaderboard_monthly month="5" year="2025" per_page="20" hide_controls="1" hide_prizes="1"]

Displays the leaderboard for May, Year 2025, 20 records per page, with hidden pagination, month and year dropdowns, and prize table.

Either you can use shortcode directly in your PHP template files:

<?php echo do_shortcode('[leaderboard_monthly month="5" year="2025" per_page="20"]'); ?>

6. Email Notifications (PRO version)

The Leaderboard for WooCommerce plugin includes an automated email notification system to inform your top customers about their achievements and prizes.

• Email Content: Each email is a personalized congratulatory message that includes:
  • The winner’s name.
  • Their winning position (e.g., “position 1”).
  • The month and year for which they won.
  • A visual medal emoji (🥇, 🥈, 🥉) corresponding to their rank.
  • Details of the prize product(s) they won, including the product name, an image thumbnail (if available), and a direct link to the product on your store.
• Required Data: Emails are only sent if:
  • Top buyers are found for the selected month and year.
  • Prizes have been configured for all top 3 positions for that specific month and year.
  • The winning user has a valid email address associated with their account.
• Error Handling: The plugin logs errors if:
  • No top buyers are found.
  • Prizes are not configured for all top 3 positions.
  • A user’s email address is missing.
  • There are issues sending emails via WordPress’s wp_mail() function (e.g., server mail configuration problems).

7. CSV-file generation (PRO version)

The Leaderboard for WooCommerce plugin allows you to export leaderboard data to csv file.

From admin menu simply choose month and year you need and click “Export to csv button”

8. Frequently Asked Questions (FAQ)

How are top shoppers calculated?

The plugin calculates the monthly purchase amount or number of orders (PRO version) for each user. Only orders with the “Completed” status are taken into account.

How are prizes assigned?

You can set prizes (products from your shop) for 1st, 2nd, and 3rd places from the plugin’s admin menu (Monthly Prizes section). Free version is restricted with 1 prize for each place

9. Support

If you have questions or encounter problems not covered in this documentation, please contact our support team.