Loyalty key concepts

documentation/build/loyalty-key-concepts.mdx

@@ -0,0 +1,222 @@
+---
+title: Loyalty key concepts
+description: Standard terms and relationships used across Loyalty Hub documentation
+keywords: ['loyalty', 'loyalty hub', 'loyalty program', 'points', 'wallets', 'earning rules', 'tiers', 'rewards']
+---
+
+This article explains how the main loyalty concepts work together.
+
+Use these concepts to define:
+- what customer actions you reward
+- how points are stored and managed
+- what customers can receive or redeem
+
+## Loyalty Hub
+
+Loyalty Hub is the module where you build and manage loyalty programs.
+
+You use Loyalty Hub to:
+- create loyalty programs
+- configure how customers earn points
+- define how points behave
+- connect wallets, earning rules, rewards, tiers, and benefits
+
+## Loyalty program
+
+A loyalty program is a configured loyalty setup.
+
+To run a points-based loyalty program, you need:
+- point wallet
+- earning rules
+
+A loyalty program can also include:
+- rewards
+- tier structures
+- benefits
+
+A single loyalty program can include multiple point wallets.
+
+## Loyalty member
+
+A loyalty member is a customer enrolled in a loyalty program.
+
+Loyalty membership is program-specific. The same customer can be a member of multiple loyalty programs.
+
+## Designer
+
+The Designer is where you configure and connect the building blocks of a loyalty program.
+
+You use the Designer to combine:
+- earning rules
+- point wallets
+- tier structures
+- rewards
+- benefits
+
+## Program building blocks
+
+The main building blocks define how customers earn, store, spend, and redeem points.
+
+### Point wallet
+
+A point wallet stores and manages points.
+
+It controls how points are stored, activated, expired, earned, spent, refunded, and used for order payments.
+
+<AccordionGroup>
+
+<Accordion title="Pending points">
+
+Pending points define when earned points become available to a loyalty member.
+
+Points can be available immediately or delayed until a later time, for example after a return window.
+
+</Accordion>
+
+<Accordion title="Point expiration">
+
+Point expiration defines how long points remain valid.
+
+You can configure no expiration, expiration after a fixed period, expiration on specific calendar dates, or expiration after inactivity.
+
+</Accordion>
+
+<Accordion title="Earning limits">
+
+Earning limits control how many points a loyalty member can collect.
+
+You can define global limits or per-transaction limits.
+
+</Accordion>
+
+<Accordion title="Spending limits">
+
+Spending limits control how many points a loyalty member can use.
+
+You can define global limits or per-transaction limits.
+
+</Accordion>
+
+<Accordion title="Refunds">
+
+Refunds define what happens to points when an order is refunded or canceled.
+
+For example, earned points can be removed or spent points can be returned.
+
+</Accordion>
+
+<Accordion title="Pay with points">
+
+Pay with points lets loyalty members use points to pay for orders.
+
+When enabled, members can pay with points based on an exchange ratio formula.
+
+</Accordion>
+
+</AccordionGroup>
+
+### Earning rule
+
+An earning rule defines when customers receive points or another configured result for their actions.
+
+Each earning rule includes a trigger, optional conditions, and one or more effects.
+
+<AccordionGroup>
+
+<Accordion title="Trigger">
+
+A trigger defines when an earning rule runs.
+
+Examples include order paid and custom event.
+
+</Accordion>
+
+<Accordion title="Conditions">
+
+Conditions define when an earning rule applies.
+
+For example, a rule can apply only when an order meets specific criteria.
+
+</Accordion>
+
+<Accordion title="Effects">
+
+Effects define what happens when an earning rule runs.
+
+For example, an effect can add points to a point wallet.
+
+</Accordion>
+
+<Accordion title="Earnings">
+
+Earnings define the conditions and effects for earning points.
+
+For example, an earning can grant fixed points, proportional points, or a benefit.
+
+</Accordion>
+
+<Accordion title="Trigger limits">
+
+Earning frequency controls how often an earning rule can run.
+
+You can configure the rule to run every time the trigger occurs or only within defined limits or time periods.
+
+</Accordion>
+
+</AccordionGroup>
+
+### Tier structure
+
+A tier structure groups loyalty members into levels.
+
+You can base tiers on criteria such as current point balance or total points earned.
+
+Tier structures are optional.
+
+<AccordionGroup>
+
+<Accordion title="Tier">
+
+A tier is a level in a loyalty program, for example Bronze, Silver, or Gold.
+
+</Accordion>
+
+<Accordion title="Tier expiration">
+
+Tier expiration defines how long a loyalty member keeps a tier.
+
+</Accordion>
+
+<Accordion title="Tier downgrade">
+
+Tier downgrade happens when a loyalty member no longer meets tier requirements.
+
+</Accordion>
+
+</AccordionGroup>
+
+### Benefits
+
+A benefit is value granted automatically when defined conditions are met.
+
+Benefits are optional.
+
+### Rewards
+
+A reward is what loyalty members redeem using points.
+
+Examples include discount coupons, gift cards, and physical rewards.
+
+Rewards are optional.
+
+## How it works
+
+A simplified loyalty flow looks like this:
+
+![How points move through a loyalty program](/images/docs/loyalty-point-flow.png)
+
+1. A customer performs an action.
+2. An earning rule is triggered.
+3. The earning rule applies effects, for example adding points.
+4. Points are stored and managed in a point wallet.
+5. The loyalty member can use points to redeem rewards, qualify for tiers, or receive benefits.

documentation/docs.json

@@ -251,7 +251,8 @@
                   "build/earning-rules",
                   "build/loyalty-points",
                   "build/loyalty-tiers",
-                  "build/loyalty-card-import"
+                  "build/loyalty-card-import",
+                  "build/loyalty-key-concepts"
                 ]
               },
               {