Skip to main content

​
Loyalty & Rewards architecture

​
Runtime stack

​
System architecture

The app runs as an embedded Shopify app inside a Shopify Admin iframe. Shopify extensions provide storefront, customer-account, checkout, and POS surfaces. The React Router server handles admin routes (loaders + actions), app proxy endpoints (storefront API), webhook handlers, and POS API endpoints.

​
Business logic services

  • Loyalty Service — points ledger, earning rules engine, balance management.
  • Rewards Service — discount code creation, redemption, reward catalog.
  • Referrals Service — two-sided rewards, fraud prevention, click tracking.
  • Campaigns Service — bonus-point campaigns with scheduling.
  • Communications — email (Resend) and SMS (Twilio) notification dispatch.
  • Analytics Service — KPI snapshots, cohort benchmarking.
  • Billing Service — plan management, app-managed Shopify Billing API.
  • Event Bus — domain event recording and outbound webhook delivery.
  • Fraud Detection — velocity checks, duplicate account detection, risk scoring.
  • Store Credit — Shopify native store credit synchronization.
  • Memberships — paid membership programs.
  • Wallet Passes — Apple Wallet and Google Wallet pass generation.
  • Social Rewards — social media action rewards.
  • Tier Downgrade — automated VIP tier demotion.
  • AI Advisor — Cloudflare AI Gateway-powered recommendations.
  • Migration — CSV import from competitor loyalty apps.

​
Extensions

​
Product data flow

The loyalty ledger records point activity in PostgreSQL. The app synchronizes loyalty data to Shopify metafields (95 definitions across customer, shop, product, collection, order) and metaobjects (13 types: reward definitions, VIP tiers, tier perks, achievements, missions, membership plans, bonus campaigns, popups, loyalty program settings, function config). Theme code calls the signed /apps/loyalty/* app proxy. Shopify forwards the corresponding path to /api/loyalty/*. The storefront proxy API handles customer data, redemption, referrals, history, popups, social actions, wallet passes, SSE notifications, self-enrollment, visit tracking, and reviews.

​
Data flow: order points award

When Shopify sends an orders/paid webhook, the webhook handler verifies the HMAC signature, checks idempotency, calculates points (with tier multiplier), creates a ledger entry, updates the customer balance, evaluates earning rules, detects velocity anomalies, evaluates VIP tier progression, evaluates achievements, and sends notifications.

​
Data flow: reward redemption

Customers redeem rewards through the checkout, POS, or storefront extension. The endpoint validates authentication and points balance, deducts points, creates a Shopify discount code via GraphQL, persists the redemption record, and returns the discount code to the extension.

​
Shopping data definitions

The app uses a single $app namespace for every metafield and metaobject. All 95 metafield definitions and 13 metaobject types are TOML-defined and auto-installed on shopify app deploy. Customer snapshots include 38+ fields covering points, tier state, referrals, and engagement counts. Customer tags (loyalty-member, vip-{tier}, referrer, loyalty-opted-out) are auto-managed. Pcnaid Documentation › Shopify Ecosystem › Loyalty & Rewards › Developer › Architecture overview › Loyalty & Rewards architecture