> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# v2.413.1

> Released July 2, 2026

## 🔴 Release v2.413.1

⭐⭐ Moderate Complexity • 20 commits • 174 files

<Note>
  Shopify loyalty integrations go natively on-site with a full loyalty hub, customer account pages, and points-after-purchase displays. Admin gets deeper widget styling controls, and critical fixes restore webhook accuracy for revenue tracking.
</Note>

## What's New

* **Shopify Loyalty Hub** – Full-page loyalty experience that inherits your store's theme styling, letting customers see tiers, points progress, and achievements natively on their account
* **Customer Account Points Display** – Native Shopify customer account page showing loyalty balance, tier status, and tier progress
* **Points After Purchase** – Automatically show customers their earned points on the order confirmation page
* **Widget Styling Customization** – Control points display format and animation/sound preferences directly from the admin panel
* **Admin Sidebar Reorganization** – Cleaner widget editor layout with improved section ordering and visibility options
* **Hero Background Customization** – Upload and customize hero banner images in widget branding settings
* **Challenge Copy Performance** – Faster challenge duplication workflow in the admin panel
* **Live Preview Auto-Reload** – Widget editor live preview now automatically refreshes when you save game config changes
* **Shopify Webhook Restoration** – Re-enabled order and refund webhooks critical for accurate points-for-spend tracking

## Apps Updated

<CardGroup cols={3}>
  <Card title="User App" icon="mobile">
    — No changes
  </Card>

  <Card title="API" icon="server">
    ✓ Updated - Entitlements foundation
  </Card>

  <Card title="Admin" icon="gear">
    ✓ Updated - Widget styling & preview improvements
  </Card>

  <Card title="MCP Server" icon="robot">
    ✓ Updated - Model optimization
  </Card>

  <Card title="Website" icon="globe">
    — No changes
  </Card>

  <Card title="Games" icon="gamepad">
    ✓ Updated - Rendering fix
  </Card>
</CardGroup>

## Detailed Changes

<AccordionGroup>
  <Accordion title="Shopify App — Loyalty Integrations" icon="store">
    ### New Features

    **NJ-1316: Full-Page Loyalty Hub with Customer Account UI Extension**

    * Theme-inherited loyalty hub page showing points, tier progress, and achievements
    * New Customer Account UI Extension (`loyalty-account-page`) rendering natively in Shopify's customer account interface
    * Deep links to theme editor for merchants to customize appearance
    * Comprehensive test coverage with Playwright harness specs
    * Responsive design matching Shopify's customer account styling

    **NJ-1322: Points After Purchase On-Site Content**

    * New order-points extension showing earned points on order confirmation page
    * Backend handler (`order-points-context.handler.server.ts`) calculates point value from order total
    * Dedicated API route for frontend context resolution
    * Full test coverage with Playwright harness specs

    **NJ-1323: Customer Account Points Banner**

    * Points summary banner in customer account interface
    * New `loyalty-account-banner` UI Extension
    * Dedicated fetch handler with caching for loyalty summary data
    * Test coverage with Playwright harness specs

    ### Fixes

    **NUDJ-0000: Restore Shopify Webhooks for Revenue Accuracy**

    * Re-enabled `orders/paid` and `refunds/create` webhook subscriptions
    * Critical fix ensuring points-for-spend calculations are accurate
    * Both standard and custom shop webhooks verified

    **NJ-1196: Storefront Widget Identity Fix**

    * Fixed opening widget via app proxy identity authentication
    * Proper CORS handling for cross-origin widget requests

    **NJ-1357: Points Config Token Refresh**

    * Fixed stale write errors (409 STALE\_WRITE) when toggling birthday effects
    * Token refresh now occurs before mutations
  </Accordion>

  <Accordion title="Admin App — Widget Editor & Customization" icon="gear">
    **NJ-1379: Widget Styling Enhancements**

    * Added "Points & Labels" section to widget styling sidebar
      * Control how points are displayed to customers
      * Customize label text and formatting
    * Added "Animations & Sounds" section
      * Enable/disable animation effects
      * Control sound feedback preferences
    * Both sections integrated into the main Styling accordion

    **NJ-1376: Sidebar Reorganization**

    * Reordered Loyalty Widget editor sections for better UX
    * Display Mode moved to top of Styling (visual consistency with landing state)
    * Launch group moved to end (terminal "go live" step)
    * Logged-Out State surfaced more prominently in Content group
    * Better section labeling and icon assignment

    **NJ-1377: Hero Background Customization**

    * Added background image uploader to Hero Settings
    * Merchants can now customize hero section appearance
    * Image validation and optimization included

    **NJ-1385: Live Preview Auto-Reload**

    * Widget editor live preview now automatically refreshes when game config saves
    * Preview state stays in sync with editor changes
    * Eliminates manual refresh when testing game-specific widget behavior

    **NJ-1378: Preview Z-Index Fix**

    * Live widget preview locked below editor overlay controls
    * Fixes z-index stacking issues preventing interaction with editor overlays

    **NJ-1384: Challenge Copy Performance**

    * Optimized challenge duplication workflow
    * Faster processing of challenge templates
    * Improved UX for merchants bulk-creating challenges

    **NJ-1387: Scratch Card Empty State**

    * Fixed Rewards step empty state to show "Add Prize Image" button
    * Better UX guidance when setting up scratch card prizes
  </Accordion>

  <Accordion title="Games App" icon="gamepad">
    **NJ-1389: Scratch Card Rendering Fix**

    * Fixed default export of scratch card component
    * Scratch card now renders correctly when accessed via Play
    * Resolved session-game-wrapper integration issue
  </Accordion>

  <Accordion title="API" icon="server">
    **NJ-874: Entitlement Usage & Subscription Features (Stack Base)**

    * New entitlement usage overview queries
    * Community-level entitlement usage tracking
    * Organisation-level usage aggregation
    * Subscription update mutation with entitlement validation
    * Foundation for upcoming subscription/feature-gating features
    * Full test coverage with 200+ test cases
    * Handles edge cases: max-community detection, period resets, limit enforcement
  </Accordion>

  <Accordion title="MCP Server" icon="robot">
    **NJ-1324: Eval Judge Model Optimization**

    * Eval judge now points at admin default model (kimi-k2.7-code)
    * Improved consistency with admin model selection
    * Dead code cleanup and deduplication
  </Accordion>
</AccordionGroup>

## Customer Impact

### Shopify Merchants

* **Loyalty visibility**: Points and tier status now appear natively in Shopify's customer account — customers can monitor progress without leaving Shopify
* **Conversion uplift**: Points-after-purchase display reinforces purchase value and encourages repeat purchases
* **Native experience**: All loyalty features inherit store theme styling automatically — no disjointed third-party widgets
* **Revenue accuracy**: Restored webhook tracking ensures points-for-spend calculations are precise

### Platform Admins

* **Widget control**: Full styling customization over points display format and animations
* **Faster setup**: Challenge copy is now faster, reducing time spent duplicating templates
* **Live testing**: Auto-reloading live preview when game settings change lets you verify behavior instantly
* **Brand consistency**: Hero background customization extends branding across widget appearance

## Breaking Changes

None — this release is fully backwards compatible.

## Technical Notes

**Shopify UI Extensions Architecture:**

* Three new Customer Account UI Extensions add 2.6 KB of new Preact components (uncompressed)
* Extensions authenticate via Shopify session tokens verified server-side
* All extensions reuse shared `fetchLoyaltyData` handler for consistent data fetching
* CORS wildcard headers used for Worker-scoped null-origin requests

**Entitlements Groundwork:**

* New `count-org-max-community-usage` and `get-entitlement-usage-overview` queries provide the data layer for upcoming feature-gating
* Mutation updates to `update-subscription` allow changing entitlements in response to plan changes
* Period-aware logic handles community-level resets and limit enforcement

**Performance:**

* Challenge copy now batches operations, reducing API round-trips
* Widget preview refresh now only triggers on explicit game-config saves (no polling)

## Contributors

<CardGroup cols={4}>
  <Card>
    <img src="https://github.com/erek_d@me.com.png" alt="Derek Counihan" style={{borderRadius: '50%', width: 48}} />

    **Derek Counihan**

    7 commits • +10,938/-6,358 lines
  </Card>

  <Card>
    <img src="https://github.com/solicshop@gmail.com.png" alt="Mo" style={{borderRadius: '50%', width: 48}} />

    **Mo**

    7 commits • +112/-43 lines
  </Card>

  <Card>
    <img src="https://github.com/dch@wenudj.com.png" alt="DCH" style={{borderRadius: '50%', width: 48}} />

    **DCH**

    3 commits • +635/-307 lines
  </Card>

  <Card>
    <img src="https://github.com/jamescockayne.png" alt="James Cockayne" style={{borderRadius: '50%', width: 48}} />

    **James Cockayne**

    1 commit • +518/-65 lines
  </Card>

  <Card>
    <img src="https://github.com/tomcarroll09@duck.com.png" alt="Tom Carroll" style={{borderRadius: '50%', width: 48}} />

    **Tom Carroll**

    1 commit • +135/-20 lines
  </Card>
</CardGroup>

## Release Stats

| Metric        | Value       |
| ------------- | ----------- |
| Total Commits | 20          |
| Lines Added   | +12,616     |
| Lines Removed | -6,741      |
| Files Changed | 174         |
| Release Size  | 🔴 Massive  |
| Complexity    | ⭐⭐ Moderate |

***

*v2.413.1 deployed on July 2, 2026*