G3N Retail Stack Story

Appearance

CRM & Loyalty ​

Status: Implemented (core customer + loyalty + stored value; consent/merge governance and fraud/abuse controls complete).

Purpose ​

CRM & Loyalty manages customer accounts (B2C and B2B), consent/governance, loyalty ledgers, gift cards, and store credits.

Goals ​

  • Provide a unified customer profile and consent governance.
  • Support loyalty earn/redeem rules with auditability and reversals.
  • Manage gift card and store credit liabilities.
  • Enable reliable customer lookup for high-velocity operations.
  • Support wholesale/B2B account structures (company + contacts + roles) and credit/terms governance.

Non-goals ​

  • CRM does not manage system users (UAS owns user identity).
  • CRM does not define pricing rules (owned by PPM).
  • CRM does not define sellability (owned by PMC).

Scope and gating ​

  • All customer data is org-scoped.
  • Channel context is captured when loyalty or tender is used.
  • Facility context applies when loyalty or tender policy differs by facility.

Request context checklist ​

  • Org: required for all customer and loyalty operations.
  • Channel: required when loyalty or tender is applied.
  • Facility: required when policy is facility-specific.
  • Actor + role: required for privacy actions and manual adjustments.
  • Cost-centre: optional attribution for billing and audit.

Core business entities and relationships ​

  • Customer accounts and contacts (B2C and B2B).
  • B2B accounts with contract terms, credit limits, and credit-hold posture.
  • B2B contacts tied to accounts with roles (buyer, approver, payer, sales rep).
  • Consent and preference records for privacy and outreach.
  • Loyalty ledger, tiers, and expiration rules.
  • Loyalty program policy (earn/redeem mode, tier rules, SKU/category multipliers, tender eligibility, redemption caps, and expiry policy).
  • Home-store assignment for settlement and liability allocation.
  • Loyalty adjustments and exception records (bonus/deduction with approval and audit).
  • Gift card and store credit balances.
  • Tax exemption profiles and certificates with validity windows.

Lifecycle and status model (described in words) ​

  • Customer records can be created, merged, suspended, or marked inactive.
  • Consent states control allowable outreach and data usage.
  • Loyalty points accrue, are redeemed, expire, and reverse on returns/voids; exchanges preserve a net ledger balance.
  • Gift cards and store credits are issued, redeemed, and may expire.

End-to-end workflows ​

Happy paths ​

  • Customer creation and contact management.
  • Loyalty earn on purchase and redeem on checkout.
  • Gift card issuance and redemption with liability tracking.

Exceptions and edge cases ​

  • Dedupe and merge workflows with audit trails.
  • Dedupe identification uses exact-match signals (primary email/phone/customer code/external refs); fuzzy/partial matching is out of scope.
  • Operational customer lookup supports partial-match search for call-center and POS workflows (separate from dedupe).
  • Loyalty reversals on returns and cancellations.
  • Fraud/abuse flags, risk assessments, and automated holds to review or restrict usage.
  • Privacy requests that limit outreach or data usage.

Configuration and defaults ​

  • The platform is enterprise-grade by default; applications may hide complexity via defaults.
  • Loyalty rules include earn rates, tiers, expiration, redemption policies, and tender eligibility.
  • Gift card and store credit policies include issuance rules and expiry (where allowed).
  • Consent and privacy flags must be enforceable for all customer interactions.
  • Tax exemption certificates are tracked with validity, scope, and renewal windows.
  • Exemption certificates are managed via /crm/exemption/certificate/create|get|list and /crm/exemption/certificate/status/set and referenced by SCM tax quote/finalize.
  • B2B accounts record terms and credit posture; SCM enforces credit-hold at order time.

Loyalty program policy (best-practice requirements) ​

Participation and enrollment ​

  • Customers are global to the org and can earn/redeem across participating locations.
  • Locations have an explicit "participating" flag (on/off) to control go-live readiness.
  • Enrollment defaults are org policy (e.g., auto-enroll on first purchase, VIP card required, or explicit opt-in).
  • Receipt display of current points is configurable by org and channel.

Earning policy ​

  • Base earn rate is defined in points per unit of home currency.
  • Tier multipliers apply on top of base earn (e.g., Bronze/Silver/Gold).
  • SKU/category/brand/supplier multipliers or exclusions are supported (including markdown and discount eligibility rules).
  • Tender eligibility is configurable per tender type with per-tender earn factors (0-100%); 0% disables earning while still allowing tender use.
  • Gift card purchases do not earn points, but redemption using gift cards can earn if the tender is eligible.
  • Points are calculated on net-of-tax when tax is added, and on tax-included prices when tax is included.
  • Example: allow 100% earn on Visa/Mastercard, 70% on Amex, and 50% on promotional tenders.

Redemption policy ​

  • Org chooses a single redemption mode:
    • Policy A: fixed point-to-currency value (per-point redemption).
    • Policy B: tiered point buckets with increasing redemption value.
  • Redemption applies as a discount to the same transaction (taxes follow the discounted price).
  • Caps and guardrails: max redemption amount per purchase; optional daily redemption limits; channel/facility-specific exceptions.

Expiry and breakage ​

  • Points expire based on a policy window (e.g., X days from earn date).
  • Optional rolling expiry: new activity can extend available points within the window.
  • Expiry is recorded as ledger entries with policy version and reason codes.
  • Operationally, expiry can be executed as-of on demand (batch or per-customer) to enforce breakage without waiting for new transactions.
  • A scheduled sweep runs periodically to expire points for inactive customers, processing a bounded batch per run and resuming via a cursor.
  • The scheduled sweep is best-effort and auditable; large orgs can supplement with operator-controlled batch runs.

Returns, voids, and exchanges ​

  • Returns/voids reverse earned points and restore redeemed value in the ledger to avoid "points lost on return."
  • Exchanges preserve the net points balance; only the delta is applied as earn/redeem.
  • Partial returns adjust earned and redeemed portions proportionally and retain audit links to the original sale.

Manual adjustments and governance ​

  • Authorized staff can add or deduct points with reason codes and immutable audit trails.
  • Adjustments are non-editable and reversible only by compensating entries.

Settlement and reporting ​

  • Home-store assignment is used to allocate loyalty liability and cross-location settlements.
  • Reports expose earned vs redeemed by location, inter-location settlements, and breakage trends.

Legacy program import and reconciliation ​

  • Imports preserve transaction-level earn/redeem/expire/adjust entries; do not recompute historical balances.
  • Imported entries retain original timestamps, locations, and policy versions; import source is recorded for audit.
  • Home-store mappings must be explicit; missing mappings are flagged and resolved by policy before settlement.
  • Inconsistencies (negative balances, missing return links) are resolved via adjustment entries with reason codes.
  • Post-import reconciliation verifies ledger totals, settlement positions, and breakage against policy windows.

Omnichannel requirements ​

  • Support customer identity and loyalty across channels.
  • Allow cross-channel returns and loyalty reversals.
  • Preserve loyalty policy version and location participation context on every earn/redeem event.

Performance requirements ​

  • Customer lookup and loyalty balance retrieval must be near-instant.
  • Redemption and reversal operations must be fast and auditable.

Operational resilience checklist ​

  • Operations are idempotent and retry-safe; duplicate submissions do not double-apply.
  • Event emission is non-blocking; operational actions do not wait on analytics pipelines.
  • Out-of-order events are tolerated; reconciliation uses timestamps and source references.
  • Exceptions generate actionable inbox items and can be retried or reversed with audit trails.
  • Long-running workflows are resumable with explicit state checkpoints.

Training and change management ​

  • Policy and workflow changes include training notes and operational checklists.
  • Critical changes use staged rollout with rollback guidance to reduce operational risk.
  • Support runbooks cover common privacy requests, loyalty disputes, and tender exceptions.

BI and KPI expectations ​

  • Active customers, retention, churn, and repeat rate by channel.
  • Loyalty liability, earn vs redeem, and breakage rate.
  • Tier distribution, migration rate, and abuse flags.
  • Home-store settlement balances and cross-location redemption impact.
  • Gift card and store credit utilization with liability deltas.
  • Consent coverage and privacy compliance coverage.

KPI readiness checklist ​

  • Customer identity records include lifecycle status and merge history.
  • Consent states are captured for all active customers.
  • Loyalty ledger entries record earn, redeem, expiration, and reversal.
  • Loyalty policy versions and tender eligibility rules are recorded per event.
  • Home-store assignment exists for settlement reporting.
  • Gift card and store credit balances record issuance and redemption.
  • Channel and facility context are captured where loyalty is applied.

Rebalancing and recalibration ​

  • Recalibrate earn and redeem rates to manage liability and engagement.
  • Adjust tier thresholds to stabilize migration and reduce churn.
  • Rebalance targeted offers based on retention and abuse signals.

Downstream accounting and integration capture ​

  • Loyalty and tender events capture org, facility, channel, customer, amounts, timestamps, and source references.
  • Liability tracking is auditable and traceable to originating transactions.
  • Inter-location settlement positions (home-store vs redeeming location) are captured for finance reconciliation.
  • Liability reporting readiness is required for finance systems.
  • Events include optional cost-centre attribution for billing and audit.

Comments and inbox ​

  • Customer records and loyalty events support comments, threads, and attachments with revision history.
  • Privacy or fraud flags can generate inbox notifications.
  • Endpoints: POST /crm/comment|comment/get|comment/list|comment/revise|comment/status|comment/report and POST /crm/inbox/create|get|list|status|state.

Governance and roles ​

  • Org roles for CRM management and privacy governance (crm_* roles).
  • Loyalty and gift card administration roles with audit oversight.
  • Role grants can be permanent, time-bounded, or scheduled.

Relationships and data flow ​

  • SCM consumes customer identity and loyalty balances for orders and returns.
  • PPM pricing rules may reference customer tiers.
  • Influencer/Affiliate may link referrals to customer identities.

Example scenarios and acceptance criteria ​

Scenario 1: Loyalty earn and reversal ​

  • A customer earns points on a purchase.
  • A return is processed and points are reversed.
  • Acceptance: the ledger reflects earn and reversal with audit trace.

Scenario 2: Cross-location earn/redeem with settlement ​

  • A customer earns points at Location A and redeems at Location B.
  • The system records home-store and settlement balances.
  • Acceptance: settlement reports show Location B redemption liability against Location A.

Scenario 3: Gift card issuance and redemption ​

  • A gift card is issued and later redeemed.
  • Balance updates and liability tracking are recorded.
  • Acceptance: balances are accurate and audit history is complete.

Scenario 4: Return after full redemption ​

  • A customer redeems points to cover most of a purchase, then returns the item.
  • Acceptance: points are restored and net refund/discount is reconciled without loss of customer points.

Scenario 5: B2B account lifecycle ​

  • A wholesale account is created with multiple contacts.
  • Contacts are assigned buyer/approver roles and account terms/credit limits are set.
  • Consent and communication preferences are recorded per contact.
  • Acceptance: account governance is enforced, terms/credit are visible, and changes are traceable.

Scenario 6: Tender earn factor by payment type ​

  • A purchase is split between Visa (100% earn) and Amex (70% earn).
  • Loyalty applies per-tender factors and records the policy version.
  • Acceptance: earned points reflect tender factors and remain auditable.

Scenario 7: Rolling expiry and breakage ​

  • The org uses a 365-day expiry window with rolling extension.
  • A customer makes a new purchase before expiry; older points still expire if outside the window.
  • Acceptance: the ledger records expiry events and breakage reporting matches policy.