# 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…

- Page: <https://www.datafirefly.com/en/documentation/smart-loyalty-tiers/>
- Language: en
- Last updated: 2026-07-01
- Other languages: [fr](https://www.datafirefly.com/documentation/smart-loyalty-tiers/index.md), [es](https://www.datafirefly.com/es/documentation/smart-loyalty-tiers/index.md), [de](https://www.datafirefly.com/de/documentation/smart-loyalty-tiers/index.md), [it](https://www.datafirefly.com/it/documentation/smart-loyalty-tiers/index.md), [pl](https://www.datafirefly.com/pl/documentation/smart-loyalty-tiers/index.md), [nl](https://www.datafirefly.com/nl/documentation/smart-loyalty-tiers/index.md), [pt](https://www.datafirefly.com/pt/documentation/smart-loyalty-tiers/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## 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.

**Compatibility:** HPOS-ready, Cart & Checkout blocks, Polylang Pro and WPML, WordPress Multisite. Tested up to WooCommerce 9.5.

## 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).

**Requirements:** WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+ (8.1+ recommended). The plugin refuses to activate if WooCommerce is not installed and active.

## 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

You can add as many tiers as you want. Recalculation happens automatically on every point award, with an hourly cron safety net for consistency.

## 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.

**Support:** For any question not covered here, contact our priority support at [support@datafirefly.com](mailto:support@datafirefly.com). Response within 24 business hours during your included support year.