Skip to main content

​
🔴 Release v2.272.1

⭐⭐⭐ Complex • 11 commits • 243 files
Massive release shipping Shopify storefront widgets for loyalty engagement, tier-based reward configuration, and significant admin UI enhancements. This release transforms how brands showcase loyalty programs on their storefronts and gives admins granular control over tier entry rewards.

​
What’s New

  • Loyalty Account Widget – New Shopify storefront widget displaying customer tier status, progress, and transaction history
  • Ways to Earn Widget – Showcase all ways customers can earn points and rewards directly on storefront
  • Tier Entry Rewards – Configure exclusive rewards that customers receive when joining specific loyalty tiers
  • Loyalty Tier Event Hooks – Backend event system for tier-driven points transactions and custom actions
  • Unified Referral System – Simplified referral URL handling with standalone widget for better code maintainability
  • Enhanced Admin Analytics – New analytics components for achievements, challenges, rewards, and leaderboards
  • Visual Design Consistency – Fixed contrast issues on user app badges and improved color theme adherence
  • Improved Admin Navigation – Level settings now in sidebar with removed dead code paths

​
Apps Updated

User App

✓ Updated - 3 changes (visual refinements)

API

✓ Updated - 4 major changes (tier configuration, event hooks)

Admin

✓ Updated - 6 major changes (tier rewards, analytics, navigation)

Shopify App

✓ Updated - 2 major widgets + handlers

Games

✓ Updated - 1 fix (tutorial scrolling)

MCP Server

— No changes

​
Detailed Changes

  • Loyalty Account Widget – Full-featured customer dashboard showing tier details, progress bars, available rewards, and transaction history
  • Ways to Earn Widget – Display challenge opportunities, actions, referral bonuses, and seasonal promotions
  • Loyalty Hub Handlers – API routes for aggregating loyalty account data (tier, points, transactions, rewards)
  • Ways to Earn Service – Service layer for preparing earning card metadata with transaction descriptions
  • Coupon Mapper – Utility for translating between Nudj rewards and Shopify discount codes
  • Tier Progress Helper – Calculate and display tier progression with visual progress indicators
  • Transaction Descriptions – Human-readable descriptions for points changes (challenges, rewards, bonuses)
  • Widget Assets – Liquid templates, CSS styling, and JavaScript interactivity for both widgets
  • Comprehensive Test Suite – 200+ tests for handlers, services, and helpers
  • Tier Entry Reward Configuration – New form section to assign rewards when users join loyalty tiers
  • Tier-Scoped Rewards – Select multiple rewards per tier with entry reward rules
  • Tier Card UI – Enhanced tier management cards showing entry reward assignments
  • Form Coordinator – Service to manage tier reward save operations and conflict resolution
  • Loyalty Tier Config Schema – Zod validation for tier configuration including entry reward rules
  • Mapper Functions – DTO conversion for loyalty tier config and state models
  • Database Migration – Migrate loyalty tier IDs from string to MongoDB ObjectId (20260401131023)
  • Admin Analytics Components – New analytics sections for achievements, challenges, rewards, posts, games, leaderboards, streaks, and quick actions
  • Sidebar Navigation – Added level settings to main settings sidebar; removed dead XP settings page
  • Achievement Form Improvements – Refined form styling and preview messaging
  • Points Transaction Hook – Event-driven service for tier-aware points transactions
  • Loyalty Tier Service Enhancements – Support for tier entry rewards in service layer
  • Update Loyalty Tier Config Mutation – tRPC endpoint for saving tier configuration changes
  • Loyalty Tier State DTO – Extended DTO with tier-scoped reward information
  • Community DTO Adjustments – Updated community model for loyalty tier ObjectId references
  • Entry Reward Mapper – Convert between form inputs and store models
  • Comprehensive Test Coverage – 76+ new tests for tier-scoped operations
  • XP Badge Contrast Fix – Improved contrast on XP badge display in leaderboard context
  • Leaderboard Title Styling – Enhanced readability of leaderboard titles
  • OTP Input Styling – Updated OTP border color to match primary theme color
  • Avatar Fallback Color – Avatar placeholders now use primary brand color for consistency
  • Tutorial Screen Scrollability – Fixed tutorial screen overflow on desktop browsers
  • Client Layout Adjustments – Improved responsive behavior for taller content
  • Design System i18n – Added new translation keys for widget labels and tier terminology
  • Database Migrations – ObjectId migration for loyalty tier references; referral code idempotency index
  • Referral Code Simplification – Removed per-community referral URL overrides (consolidated to single approach)
  • Test Infrastructure – Fixed flaky MongoMemoryReplSet tests in service test suite
  • Models & DTOs – Updated loyalty tier and referral code models for simplified architecture

​
Detailed Feature Breakdown

​
Loyalty Account Widget

The Loyalty Account Widget brings customer loyalty status directly to your Shopify storefront, enabling customers to see their progress and available rewards without leaving your store. Customer Experience:
  • View current tier and progress toward next tier with visual progress bar
  • See earned and available points balance at a glance
  • Browse available rewards redeemable in current tier
  • Review recent transaction history (points earned, rewards redeemed)
  • Access referral information and rewards
Admin Configuration:
  • Enable/disable widget on any storefront page
  • Configure which tier progress data to display
  • Select reward display options (all rewards, tier-scoped, featured)
  • Customize colors to match brand theme
Technical Implementation:
  • Dedicated API handlers for loyalty data aggregation
  • Service layer for tier progress calculation and formatting
  • Dynamic coupon mapping for Shopify discount integration
  • Efficient data fetching with caching strategies
  • 200+ test cases ensuring data accuracy

​
Ways to Earn Widget

The Ways to Earn Widget showcases all the engagement opportunities available to your customers, driving discovery and participation. Features:
  • Display challenges and their point rewards
  • Show actions (surveys, referrals, social shares) with earning potential
  • Highlight seasonal promotions and bonus earning periods
  • Surface tier-specific earning opportunities
  • Include transaction descriptions explaining point changes
Earning Card Types:
  • Challenge Cards – Challenge name, points, tier availability
  • Action Cards – Action name, action type, points per completion
  • Referral Cards – Referral earning structure and terms
  • Promotion Cards – Time-limited bonus earning opportunities
Admin Configuration:
  • Control which earning types are visible
  • Reorder cards to highlight preferred earning methods
  • Configure card descriptions and styling
  • Enable/disable seasonal promotions

​
Tier Entry Rewards

Tier Entry Rewards give you granular control over the customer experience at each loyalty tier level, enabling tier-specific onboarding incentives and progression rewards. Admin Features:
  • Assign multiple rewards to tier entry events
  • Set tier-specific reward rules and conditions
  • Configure entry bonuses and welcome incentives
  • Preview how rewards will appear to customers
Customer Experience:
  • Automatically receive tier entry rewards when upgrading
  • See welcome gifts and bonuses in reward details
  • Understand tier-specific benefits and incentives
  • Drive engagement and reduce churn at tier transitions
Use Cases:
  • Welcome bonus when entering Bronze tier (100 points)
  • Tier upgrade gift (exclusive digital reward)
  • Anniversary bonus for long-term tier members
  • Referral boost for newly recruited customers

​
Loyalty Tier Points Transaction Hook

Backend event system enabling sophisticated points logic tied to tier transitions and actions. Technical Capabilities:
  • Event hook fires on tier entry/exit
  • Access to previous and current tier context
  • Conditional points allocation based on tier
  • Integration with custom business logic
  • Observable and auditable transaction history
Use Cases:
  • Award bonus points on tier upgrade
  • Apply different point multipliers per tier
  • Trigger tier-specific achievement unlocks
  • Sync tier changes to external loyalty systems

​
Admin Highlights

  • Tier Entry Reward Configuration – Assign multiple rewards to each loyalty tier for welcome bonuses and progression incentives
  • Enhanced Tier Management UI – Visual tier cards showing configured entry rewards and easy editing
  • Admin Analytics Dashboard – New analytics components for achievements, challenges, rewards, posts, games, leaderboards, and streaks
  • Simplified Admin Navigation – Level settings added to settings sidebar; removed legacy XP settings page
  • Loyalty Account Data Aggregation – Behind-the-scenes data handlers for efficient widget performance
  • Event-Driven Points System – Configure tier transitions to trigger custom points logic

​
User Highlights

  • Loyalty Account View – See your tier status, points balance, and available rewards on Shopify storefronts
  • Ways to Earn Discovery – Browse all earning opportunities in an easy-to-browse widget
  • Improved Visual Design – Better contrast on XP badges and leaderboard titles for accessibility
  • Consistent Brand Colors – OTP borders and avatar fallbacks now match your theme’s primary color
  • Tier Welcome Bonuses – Automatically receive special rewards when joining new loyalty tiers (if configured by admin)

​
Breaking Changes

None in this release.

​
Technical Notes

Loyalty Tier ObjectId Migration: Loyalty tier IDs migrated from string to MongoDB ObjectId (migration: 20260401131023). All tier-related queries must use ObjectId comparisons. API client types automatically updated. Shopify Widget Architecture: Widgets communicate via dedicated API handlers (/api.proxy.*) that aggregate data from multiple services. Each widget has its own service layer (LoyaltyAccountDataService, WaysToEarnDataService) for independent scaling and testing. Referral URL Consolidation: Removed per-community referral URL override configuration. Referral system now uses unified URL structure with community context provided via URL parameters. Existing custom URLs remain functional via reverse migration. Tier Entry Reward Event Timing: Tier entry rewards are provisioned during tier assignment, before tier-scoped achievement evaluation. This ensures entry rewards are available for achievement unlocks in the new tier.
  • Loyalty Tier System
  • Rewards Management
  • Achievement System
  • Shopify Integration
  • Referral Program
  • Points & XP System
  • Admin Analytics

​
Contributors

SaadK94@SaadK943 commits • +8,401/-557 lines

dchnudj@dchnudj3 commits • +42/-335 lines

jamescockayne@jamescockayne2 commits • +2,433/-34 lines

ZuhayrK00@ZuhayrK002 commits • +290/-191 lines

erek_d@erek_d1 commit • +12,875/-855 lines

​
Release Stats

MetricValue
Total Commits11
Lines Added+24,251
Lines Removed-1,954
Files Changed243
Release Size🔴 Massive
Complexity⭐⭐⭐ Complex
v2.272.1 deployed on April 1, 2026