Smart Loyalty Tiers — Complete documentation

Introduction

Smart Loyalty Tiers is a complete loyalty program for WooCommerce. Unlike most loyalty plugins that only offer a simple points counter on purchases, Smart Loyalty Tiers ships with 5 distinct earning sources, 4 progressive VIP tiers with concrete rewards (lifetime free shipping, early access to new products, priority support), a gamification badge system, and points-to-one-shot WooCommerce coupon redemption.

Installation and activation

1. Download the ZIP file smart-loyalty-tiers.zip from your DataFirefly customer area.
2. In WordPress, go to Plugins → Add New → Upload Plugin.
3. Select the ZIP then click Install Now.
4. Click Activate.

On activation, the plugin automatically creates 9 database tables (prefix wp_slt_), seeds the 4 tiers Bronze / Silver / Gold / Platinum, inserts 10 default achievement badges, adds the loyalty endpoint to WooCommerce My Account, and schedules 2 cron jobs (daily expiration, hourly tier recalculation).

3-minute setup

After activation, a new Loyalty menu appears in the admin sidebar with 5 subpages: Dashboard, VIP Tiers, Members, Badges, Settings.

Step 1 — Earning rates (Loyalty → Settings)

Adjust default values to fit your strategy:

• Points per currency unit spent — default: 1 (1 pt / 1 unit)
• Points per product review — default: 50
• Points per referral — default: 500
• Points per newsletter signup — default: 100
• Points per social share — default: 25

Step 2 — Coupon redemption

• Redemption rate — default: 100 points = 1 unit of discount
• Minimum redemption threshold — default: 500 points
• Coupon cap — default: 30% of cart subtotal

Step 3 — Display and gamification

• Points label — default: “points” (e.g. “miles”, “stars”, “fireflies”)
• Gamification enabled — enables the celebration overlay on tier upgrade
• Email notifications — enables tier upgrade and badge earned emails

The 4 VIP tiers

Each customer is automatically placed in a tier based on their total lifetime points (independent of coupon redemptions). The seeded tiers:

• Bronze — 0 points, no special benefits, entry tier
• Silver — 500 lifetime points, x1.25 points multiplier on purchases, 12h early access
• Gold — 2,000 lifetime points, x1.5 multiplier, free shipping, priority support, 24h early access
• Platinum — 5,000 lifetime points, x2 multiplier, lifetime free shipping, 48h early access, exclusive products, 500 birthday bonus points

From Loyalty → VIP Tiers, each tier is editable live with a color picker. Configurable benefits:

• Points multiplier (points_multiplier) — applied automatically on all points earned from purchases
• Free shipping (free_shipping) — WooCommerce package rates are zeroed at cart calculation
• Early access in hours (early_access_hours) — how many hours before a product’s embargo date this tier can see and buy it
• Priority support (priority_support) — adds an orange badge on admin orders and injects an X-Priority header in transactional emails
• Birthday bonus (birthday_bonus) — points automatically credited on the customer’s birthday (if set in profile)
• Exclusive products (exclusive_products) — enables per-tier filtering on products marked as exclusive

The 5 point sources

1. Purchases (PurchaseAction)

Points are credited when the order transitions to completed status (woocommerce_order_status_completed). The formula:

points = subtotal_excluding_tax × points_per_currency × tier_multiplier

The system is idempotent: impossible to earn twice on the same order, even if status flips. On full or partial refund, points are automatically reversed proportionally to the refunded amount.

2. Product reviews (ReviewAction)

Points are credited when an approved review is published (comment_post or transition_comment_status → approved). A “Verified buyer only” option limits earnings to reviews from actual buyers (anti-spam protection).

3. Referrals (ReferralAction)

Every user gets a unique referral code and a share link. Tracking is done via a 30-day cookie (configurable via slt_referral_cookie_days). The referrer earns points when their referee completes their first order. An optional welcome bonus is credited to the referee.

4. Newsletter (NewsletterAction)

Two trigger modes:

• Checkout checkbox — handled automatically if the box is ticked
• Public hook — do_action('slt_newsletter_subscribed', $user_id, $email) — call it from Mailchimp, Brevo, MailPoet, Klaviyo or any system

For a native form, use the [slt_newsletter_form] shortcode.

5. Social shares (SocialShareAction)

7 platforms supported via the [slt_share_buttons] shortcode: Facebook, X/Twitter, LinkedIn, Pinterest, WhatsApp, Telegram, Email. Each share is logged with an anti-abuse cap:

• Maximum 5 shares per day per user (configurable)
• The same share (user, platform, URL) only counts once

The concrete rewards

Lifetime free shipping

For tiers with free_shipping: true, all WooCommerce package rates are zeroed at cart calculation. No coupon to re-enter, no manipulation. A green notice is automatically displayed on the cart: “✨ Free shipping — VIP status”.

Early access to new products

On each product, a “Loyalty early access” metabox lets you set an embargo date (_slt_embargo_until). Until the date is reached, the product becomes:

• Not purchasable for tiers below the configured threshold (woocommerce_is_purchasable filter)
• Invisible in listings (woocommerce_product_query filter)

Tiers with early_access_hours > 0 can see and buy the product within the window defined before public embargo lift. An amber banner on the single product page informs eligible customers.

Priority support

For tiers with priority_support: true, every order placed by the customer:

• Gets an orange “Priority” badge visible in the admin order list (HPOS and legacy)
• Gets an X-Priority: high header injected in transactional emails — useful to filter in your helpdesk (Zendesk, Freshdesk, Help Scout, etc.)

Badge system (gamification)

10 achievement badges are seeded on activation:

• First Purchase — first order
• Regular Customer — 5 orders
• Power Buyer — 10 orders
• Reviewer — first review posted
• Critic — 10 reviews posted
• Brand Ambassador — first successful referral
• Influencer — 5 successful referrals
• Social Butterfly — 10 social shares
• Insider — newsletter signup
• Big Spender — 1,000 units spent lifetime

From Loyalty → Badges, edit existing badges or create new ones. Each badge has a JSON criteria:

{
  "trigger": "purchase | review | referral | social_share | newsletter | lifetime_spend",
  "count": 5,             // for count-based triggers
  "amount": 1000.00       // for lifetime_spend (currency amount)
}

A badge can also grant a bonus points reward on unlock.

Points to coupon redemption

From My Account → Loyalty, the customer enters the number of points to convert and clicks “Generate coupon”. The plugin:

1. Creates a unique one-shot WC_Coupon
2. Restricts the coupon to the customer’s email address
3. Sets a 30-day expiry
4. Deducts the points from balance and logs the transaction

A slt_max_redemption_percent cap (30% by default) prevents the coupon from exceeding a percentage of the cart subtotal — protection against margin dilution.

The 7 frontend shortcodes

[slt_balance]

Displays the logged-in customer’s points balance. Optional attribute: label="miles".

[slt_balance label="fireflies"]

[slt_tier_badge]

Displays the current tier name in a colored badge (tier color).

[slt_tier_badge]

[slt_progress_bar]

Animated progress bar toward the next tier, with points remaining and a shimmer effect.

[slt_progress_bar]

[slt_tiers_table]

Comparison table of all tiers with their thresholds and benefits — perfect for a “Loyalty program” landing page.

[slt_tiers_table]

[slt_referral_link]

Displays the customer’s unique referral link + copy button + successful referrals counter.

[slt_referral_link]

[slt_share_buttons]

Social share buttons. Attributes:

• url — URL to share (default: current page URL)
• title — title to share (default: page title)
• platforms — comma-separated list (default: all)

[slt_share_buttons platforms="facebook,twitter,whatsapp"]

[slt_newsletter_form]

Newsletter signup form with automatic points credit on subscription.

[slt_newsletter_form title="Join our VIP newsletter"]

Customer area (My Account → Loyalty)

A new Loyalty tab is automatically added after the WooCommerce My Account dashboard. The customer finds there:

• A colored hero matching their tier color, with balance and status
• Their progress bar toward the next tier
• The list of their current benefits
• The coupon redemption form (if their balance exceeds the minimum threshold)
• The grid of all badges (earned in color, locked in grey)
• Their complete transaction history (last 25 entries by default)

Admin dashboard (Loyalty → Dashboard)

The admin dashboard shows 30-day stats:

• Total members and 30-day active members
• Circulating points (sum of active balances)
• Points earned and redeemed on 30 days
• Completed referrals on 30 days
• Member distribution per tier (bars)
• Recent activity (last 20 transactions across all members)

From the Members page, you can search for a customer, see their balance and tier, and manually adjust their points (award or deduct) via an AJAX modal with a justification field.

Transactional emails

Two responsive HTML emails are sent automatically:

Tier upgrade

Sent when reaching a new tier. Contains:

• A banner in the new tier’s color with a trophy
• The list of newly unlocked benefits
• A CTA to the Loyalty area

The template can be overridden by copying it to your-theme/smart-loyalty-tiers/emails/tier-upgrade.php.

Badge earned

Sent when a new badge is unlocked, with name, description and any credited bonus points.

Developer hooks

Every plugin action fires hooks so you can extend without touching the code:

// After points awarded
do_action('slt_points_awarded', $user_id, $points, $source, $reference_id, $reference_type);

// After points deducted
do_action('slt_points_deducted', $user_id, $points, $source, $reference_id, $reference_type);

// Tier change
do_action('slt_tier_upgraded', $user_id, $new_tier, $old_tier);
do_action('slt_tier_downgraded', $user_id, $new_tier, $old_tier);

// Badge unlocked
do_action('slt_badge_awarded', $user_id, $badge);

// Successful referral
do_action('slt_referral_completed', $referrer_id, $referee_id, $order_id);

// Newsletter subscription (trigger it from your integration)
do_action('slt_newsletter_subscribed', $user_id, $email);

HPOS and Cart / Checkout blocks compatibility

The plugin automatically declares HPOS compatibility via FeaturesUtil::declare_compatibility(). All order reads use the WooCommerce CRUD API (wc_get_order()) — no direct queries on wp_posts.

Compatibility with Cart and Checkout blocks is also declared. Free shipping applies in both modes (classic and blocks).

Multilingual (Polylang and WPML)

The plugin is fully translatable via load_plugin_textdomain with the smart-loyalty-tiers textdomain. French and English are bundled, a complete POT file is included for any other language.

For multilingual sites:

• Polylang Pro — tier and badge names can be translated via the Polylang String Translations interface
• WPML — the same strings are registered with WPML via icl_register_string

FAQ and troubleshooting

A customer doesn’t see their points credited after an order

Check that the order is in completed status (the plugin does not award points on “processing” or “pending”). If status is correct, go to Loyalty → Members, search for the customer, and check their history.

Free shipping is not applied for a Gold customer

Verify in Loyalty → VIP Tiers that the “Free shipping” benefit is enabled on the Gold tier. Also clear WooCommerce session caches (wc_clear_cart_cache()).

The My Account → Loyalty endpoint returns 404

Go to Settings → Permalinks and click “Save Changes” to flush rewrite rules. This is only needed once after activation.

Cron does not fire

On low-traffic sites, WordPress cron can be irregular. Configure a real system cron to call wp-cron.php every 5–15 minutes, and disable pseudo-cron in wp-config.php:

define('DISABLE_WP_CRON', true);

A customer complains about points removed after a full refund

This is normal behavior: on full or partial refund, the corresponding points are automatically deducted. If the customer insists, you can manually re-credit points via Loyalty → Members → Adjust.

How do I disable points expiration?

In Loyalty → Settings, set “Expiration duration” to 0 days. Points will never be purged.