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 | Dependency | Version | |---|---| | PHP | ^8.2 | | Sylius | ~2.1 | | Symfony | ^7.0 | ## Installation ### 1. Register the plugin ### 2. Import routes ### 3. Extend your Order entity Add the loyalty trait to your Order entity so customers can redeem points on the cart page: ### 4. Register the Stimulus controller (for the cart widget) Add the plugin JS dependency to your `package.json`: Register the controller in `assets/shop/controllers.json`: Then rebuild assets: ### 5. Run migrations ### 6. Seed the default configuration 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 ## Architecture ### Domain Model Points are **shared across channels** (one account per customer), while earning/redemption rates are **configured per channel**. ### Entities | Entity | Purpose | |---|---| | `LoyaltyAccount` | Per-customer account with balance, lifetime points, tier | | `PointTransaction` | Ledger entry — signed points, type, optional order link, expiry | | `LoyaltyTier` | Tier with min-points threshold, earning multiplier, color | | `LoyaltyConfiguration` | Per-channel config: earning rate, redemption rate, expiry, bonuses | | `LoyaltyRule` | Per-product earning rate override, multi-channel | ### Sylius Integration Points | Extension Point | What It Does | |---|---| | `OrderProcessorInterface` (priority 5) | Applies loyalty discount adjustment after taxes | | `sylius.order.post_complete` event | Awards earn points + first-order bonus on order completion | | `sylius.order.post_cancel` event | Revokes earned points | | `sylius.customer.post_register` event | Awards registration bonus | | `workflow.sylius_order_checkout.completed.complete` | Deducts redeemed points from balance | | `workflow.sylius_order.completed.cancel` | Restores redeemed points | | `workflow.sylius_payment.completed.refund` | Restores redeemed points on refund | | `sylius.menu.admin.main` event | Adds menu items under Customers, Marketing & Configuration | | Twig hooks | Cart widget, cart/checkout summary, customer show section, account menu | ## Multi-Channel Support Each Sylius channel can have its own loyalty configuration: | Setting | US Store | EU Store | B2B Store | |---|---|---|---| | Earning rate | 1 pt / $1 | 2 pts / €1 | Disabled | | Redemption rate | 100 pts = $1 | 50 pts = €1 | N/A | | Registration bonus | 100 pts | 200 pts | 0 | | Birthday bonus | 200 pts | 500 pts | 0 | | Tiers enabled | Yes | Yes | No | 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. | Field | Description | |---|---| | Name | Display name (e.g., "Bronze") — code is auto-generated | | Min Points | Lifetime points threshold to reach this tier | | Multiplier | Earning multiplier (e.g., 1.5x for Silver) | | Color | Badge color (hex, rendered in admin and shop) | ### 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:** | Rule | Products | Rate | Channels | |---|---|---|---| | Double on gift sets | Gift Set A, Gift Set B | 2 pts/€1 | All | | No points on gift cards | Gift Card | 0 pts/€1 | All | | Premium bonus | Limited Edition Watch | 10 pts/€1 | Fashion Web Store | ## API Endpoints (Headless) For headless/SPA storefronts, the plugin provides REST endpoints. All shop endpoints verify the authenticated user owns the order. ### Shop API ### Admin API ## 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: | Language | File | |---|---| | English | `messages.en.yaml` | | French | `messages.fr.yaml` | | German | `messages.de.yaml` | | Spanish | `messages.es.yaml` | | Polish | `messages.pl.yaml` | | Portuguese | `messages.pt.yaml` | ## Running Tests 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](LICENSE).