README

Sylius Loyalty Plugin

A points-based loyalty and rewards system for Sylius 2.x e-commerce stores.

Overview

SyliusLoyaltyPlugin adds a complete loyalty program to any Sylius 2.x store. Customers earn points on purchases, redeem them as discounts on the cart page, unlock tier-based multipliers, and receive bonus points for registration, birthdays, and first orders — all configurable per channel from the admin panel.

Key Features

• Multi-channel — Each channel has independent earning rates, redemption rates, expiry, and bonus settings
• Loyalty rules — Override earning rates for specific products with per-rule points configuration and multi-channel support
• Points earning — Configurable default points per currency unit on every order
• Cart redemption — Spend points as a monetary discount on the cart page
• Points expiry — Automatic expiration with cron command + 30-day warnings
• Bonus events — Registration, birthday, and first-order bonuses (toggle on/off per channel)
• Tier system — Bronze / Silver / Gold with earning multipliers (tiers only go up)
• Admin panel — Full management: accounts, transactions, manual adjustments, per-channel config
• Customer account — Points balance, tier badge, paginated transaction history with running balance
• REST API — Headless-ready endpoints for balance and redemption
• Workflow integration — Points deducted on order complete, restored on cancel/refund
• Translations — English, French, German, Spanish, Polish, Portuguese

Requirements

Installation

composer require abderrahimghazali/sylius-loyalty-plugin

1. Register the plugin

// config/bundles.php
return [
    // ...
    Abderrahim\SyliusLoyaltyPlugin\SyliusLoyaltyPlugin::class => ['all' => true],
];

2. Import routes

# config/routes/sylius_loyalty.yaml
sylius_loyalty:
    resource: '@SyliusLoyaltyPlugin/config/routes.yaml'

3. Extend your Order entity

Add the loyalty trait to your Order entity so customers can redeem points on the cart page:

// src/Entity/Order/Order.php
namespace App\Entity\Order;

use Abderrahim\SyliusLoyaltyPlugin\Entity\Order\LoyaltyOrderInterface;
use Abderrahim\SyliusLoyaltyPlugin\Entity\Order\LoyaltyOrderTrait;
use Sylius\Component\Core\Model\Order as BaseOrder;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_order')]
class Order extends BaseOrder implements LoyaltyOrderInterface
{
    use LoyaltyOrderTrait;

    // ...existing code...
}

4. Register the Stimulus controller (for the cart widget)

Add the plugin JS dependency to your package.json:

{
    "dependencies": {
        "@abderrahimghazali/sylius-loyalty-plugin": "file:vendor/abderrahimghazali/sylius-loyalty-plugin/assets"
    }
}

Register the controller in assets/shop/controllers.json:

{
    "controllers": {
        "@abderrahimghazali/sylius-loyalty-plugin": {
            "loyalty-redemption": {
                "enabled": true,
                "fetch": "eager"
            }
        }
    }
}

Then rebuild assets:

npm install
npm run build

5. Run migrations

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

6. Seed the default configuration

php bin/console loyalty:install

This creates a default loyalty configuration for each channel. You can then customize settings per channel from the admin panel under Configuration > Loyalty configuration.

7. Set up cron jobs

# Expire old points (run daily)
php bin/console loyalty:expire-points

# Award birthday bonuses (run daily)
php bin/console loyalty:birthday-bonus

Architecture

Domain Model

Channel ──1:1──▶ LoyaltyConfiguration
                    (earning rate, redemption rate, expiry, bonuses)

Channel ──N:M──▶ LoyaltyRule ──N:M──▶ Product
                    (name, enabled, points rate per product)

Customer ──1:1──▶ LoyaltyAccount ──1:N──▶ PointTransaction
                        │                    (earn/redeem/expire/adjust/bonus)
                        │
                        └───N:1──▶ LoyaltyTier
                                   (Bronze/Silver/Gold)

Points are shared across channels (one account per customer), while earning/redemption rates are configured per channel.

Entities

Sylius Integration Points

Multi-Channel Support

Each Sylius channel can have its own loyalty configuration:

Points are shared across channels — a customer earns on one store and redeems on another. Rates are applied based on the order's channel.

Manage per-channel settings at Configuration > Loyalty configuration in the admin panel.

Shop Features

Cart Redemption Widget

On the cart page, logged-in customers can redeem points as a discount. The widget uses Symfony UX Live Components for seamless interaction without page reloads.

• Input field with placeholder showing available balance
• "Apply points" button (triggers Live Component re-render)
• Applied state shows a badge with points count, discount value, and a remove button
• Loyalty discount line appears in the cart summary and throughout the checkout sidebar
• Automatic clamping: can't exceed balance or order total

Customer Account — Loyalty Page

Accessible from the account sidebar menu:

• Current balance + redeemable monetary value
• Tier badge with multiplier info
• Expiry warning for points expiring within 30 days
• Paginated transaction history table with running balance column

Admin Features

Loyalty Accounts

Grid view of all customer loyalty accounts with balance, lifetime points, tier, and status. Click through to a detail page showing paginated transaction history.

Manual Point Adjustment

From any loyalty account detail page, admins can add or deduct points with a required reason field. Positive values create an Adjust (credit) transaction, negative values create a Deduct (debit) transaction.

Tier Management

Full CRUD for loyalty tiers under Marketing > Loyalty tiers. Code and position are auto-generated from the tier name.

Per-Channel Configuration

Under Configuration > Loyalty configuration, admins see a table of all channels and can configure each independently:

• Points per currency unit
• Redemption rate (points per 1 currency unit)
• Expiry period in days
• Enable/disable tier system
• Toggle and configure bonus events (registration, birthday, first order)

Settings are stored in the database and take effect immediately without redeployment.

Loyalty Rules

Under Marketing > Loyalty rules, admins can override the default earning rate for specific products. Each rule has:

• Name — descriptive label for the rule
• Products — select one or more products via autocomplete
• Points per currency unit — custom earning rate (set to 0 to exclude products from earning)
• Channels — select which channels the rule applies to
• Enabled — toggle the rule on/off

When a product in an order matches a loyalty rule for that channel, the rule's rate is used instead of the channel's default rate.

Example rules:

API Endpoints (Headless)

For headless/SPA storefronts, the plugin provides REST endpoints. All shop endpoints verify the authenticated user owns the order.

Shop API

POST   /api/v2/shop/orders/{tokenValue}/loyalty-redemption
       Body: { "pointsToRedeem": 500 }
       → { "pointsRedeemed": 500, "discountAmount": 500, "orderTotal": 9500 }

DELETE /api/v2/shop/orders/{tokenValue}/loyalty-redemption
       → { "pointsRedeemed": 0, "discountAmount": 0, "orderTotal": 10000 }

GET    /api/v2/shop/loyalty/account
       → Balance, lifetime points, tier info

Admin API

GET    /api/v2/admin/loyalty/accounts
GET    /api/v2/admin/loyalty/accounts/{id}
PATCH  /api/v2/admin/loyalty/accounts/{id}

Edge Cases Handled

• Pessimistic DB locking prevents double-spend on concurrent checkouts, cancellations, and refunds
• API endpoints require ROLE_USER and verify the authenticated user owns the order
• Balance cannot go negative (clamped in service layer + guard in entity)
• Points redemption cannot exceed available balance (clamped, validated in cart form and API)
• Discount cannot exceed order total (capped, points recalculated)
• Guest checkouts cannot use loyalty points (guarded)
• Disabled accounts are excluded from earning and redemption
• Duplicate point awards are prevented (idempotent per order)
• Duplicate revocations are prevented (idempotent per order)
• First-order bonus awarded only once (idempotent)
• Points are reserved at cart, deducted only on order completion
• Cancelled/refunded orders restore redeemed points (idempotent, locked)
• Birthday bonus awarded at most once per calendar year per channel
• Tiers only upgrade, never demote (based on lifetime points)
• CSRF protection on all admin forms
• Admin point adjustment descriptions are sanitized
• Expire points command uses batched processing for large datasets

Translations

The plugin ships with translations for:

Running Tests

composer install
vendor/bin/phpunit

71 unit tests covering entities, services, order processing, and all event listeners.

Screenshots

Cart — Redeem points

Customer Account — Loyalty points & transaction history

Admin — Loyalty tiers management

License

This plugin is released under the MIT License.