Create tier structures

documentation/build/create-tier-structures.mdx

@@ -0,0 +1,322 @@
+---
+title: Create tier structures
+description: Set up rules that group customers based on their loyalty activity
+keywords: ['tier structures', 'loyalty tiers', 'tier levels', 'tier builder', 'tier configuration']
+---
+
+Tier structures control how customers are assigned to tiers and how their tier status changes over time.
+
+
+## Create a tier structure
+
+Go to **Loyalty hub** > **Tier structures** to **Create tier structure**.
+
+The tier structure builder informs which steps require your action.
+
+<Steps>
+
+<Step>
+
+### General settings
+
+Set the basic behavior of the tier structure.
+
+**Name tier structure**: enter a name for the structure
+
+<AccordionGroup>
+
+<Accordion title="Tier type">
+
+- **Point balance**: uses the customer’s current point balance  
+- **Points earned**: uses total points earned over a tracking period  
+
+When you select **Points earned**, additional options appear.
+
+</Accordion>
+
+<Accordion title="Points earned configuration">
+
+Set how tier changes are applied.
+
+- **When to apply tier change**:
+  - **Immediately**: updates when the threshold is reached  
+  - **Next tracking period**: updates at the start of the next cycle  
+
+- **Tracking period value**: length of the tracking period
+
+- **Period unit**: Hour(s), Day(s), Week(s), Month(s), Year(s)
+
+</Accordion>
+
+<Accordion title="Card definition">
+
+Select the wallet used to calculate tiers.
+
+Start typing in **Type here to find** to search.
+
+Use **+** to create a new wallet.
+
+</Accordion>
+
+</AccordionGroup>
+
+Complete all required fields. If something is missing or invalid, you will see **Action required**.
+
+</Step>
+
+<Step>
+
+### Tier levels
+
+Set the structure of your tiers and the conditions required to reach each level.
+
+You can set up to 10 tier levels.
+
+After you define **Minimum value (points)** and **Maximum value (points)**, use **+ Add tier levels** to add another tier.
+
+<Note>
+
+Providing a valid **Minimum value (points)** enables **Create tier structure**, so you can finish the setup without completing additional steps.
+
+You can edit the configuration later.
+
+</Note>
+
+<AccordionGroup>
+
+<Accordion title="Tier setup">
+
+Each tier defines a level in your loyalty program.
+
+- **Tier name**: label of the tier (for example Bronze, Silver, Gold)
+
+- **Minimum value (points)**: points required to reach this tier
+
+- **Maximum value (points)**: upper limit of points for this tier
+
+- **Unlimited**: removes the upper limit (available only for the highest tier)
+
+  <Note>
+  If used for a lower tier, you will see:  
+  **Set a maximum value for all tiers except the highest one.**
+  </Note>
+
+- **Points range**: calculated automatically from minimum and maximum values
+
+<Note>
+When you add a new tier:
+- **Minimum value (points)** is set to one point higher than the previous tier’s **Maximum value (points)**
+- The value can be adjusted manually
+- Tier ranges must remain in order and cannot overlap
+</Note>
+
+</Accordion>
+
+<Accordion title="Advanced options">
+
+Set how customers qualify for each tier.
+
+- **Qualification Logic**:
+  - **AND**: customer must meet the points range and belong to the selected segment
+  - **OR**: customer can qualify by points or by belonging to the selected segment
+
+- **Customer segment**: segment used for tier qualification
+
+  <Note>
+  This field becomes required when **Qualification Logic** is set to **AND**.
+  </Note>
+
+- **Allow tier downgrade for this level**: allows customers to move to a lower tier
+
+  <Note>
+  Disable this option to create a fixed tier that customers keep permanently.
+  </Note>
+
+</Accordion>
+
+</AccordionGroup>
+
+</Step>
+
+<Step>
+
+### Tier expiration
+
+Set how long a customer remains in a tier and when reevaluation occurs.
+
+If you do not select an expiration option, tiers do not expire.
+
+<AccordionGroup>
+
+<Accordion title="Fixed Duration">
+
+- **Duration**: how long the tier is valid after entry  
+- **Period unit**: Day(s), Month(s), Year(s)
+
+</Accordion>
+
+<Accordion title="Calendar Expiry">
+
+- **Expiry date (MM-DD)**: date when the tier expires each year  
+
+Add at least one expiry date.
+
+</Accordion>
+
+<Accordion title="Sliding Expiry">
+
+Set expiration based on inactivity.
+
+- **Inactivity period**: time without qualifying activity before the tier expires  
+- **Period unit**: Day(s), Month(s), Year(s)
+
+- **Qualifying activities**:
+  - **Earning activities**
+  - **Spending activities**
+  - **Custom activities**
+
+If you select **Custom activities**:
+- **Custom event**: event used as a qualifying activity  
+- **+ Add activity**: adds the event to the list  
+
+Add at least one custom activity.
+
+</Accordion>
+
+</AccordionGroup>
+
+</Step>
+
+<Step>
+
+### Tier downgrade
+
+Set how customers move to lower tiers when they no longer meet qualification criteria.
+
+<AccordionGroup>
+
+<Accordion title="Downgrade options">
+
+- **No downgrade**: customers remain in their current tier
+
+- **Multi-level downgrade (full reassessment)**: customer is reassigned to the tier that matches their current qualification
+
+- **Single-level downgrade (step-by-step drop)**: customer moves down one tier at a time
+
+</Accordion>
+
+<Accordion title="Grace period">
+
+Set how long to delay the downgrade.
+
+- **Grace period before downgrade**: Enables a delay before downgrade is applied.
+- **Grace period value**: length of the delay before downgrade.
+- **Unit**: defines the duration of the grace period in Day(s), Month(s), or Year(s)
+- **Round up grace period**: rounds the grace period to the end of the selected unit
+
+<Note>
+Available only when **Multi-level downgrade** or **Single-level downgrade** is selected.
+</Note>
+
+</Accordion>
+
+</AccordionGroup>
+
+</Step>
+
+<Step>
+
+### Summary
+
+Review your configuration before saving.
+
+The summary shows all settings defined in previous steps.
+
+Use **Go to step** to return to any section and make changes.
+
+- If everything is valid, **Create tier structure** becomes available  
+- If something is incompatible, you will see **Action required**
+
+Use **Create tier structure** to finish.
+
+</Step>
+
+</Steps>
+
+## Tier structures view
+
+The **Tier structures** view lists all configurations created in your project.
+
+Each structure appears with its status and key settings.
+
+### Overview
+
+This list shows key details of each tier structure.
+
+- **Status**:
+  - **Draft**: structure has not been activated yet
+  - **Active**: structure is enabled
+  - **Inactive**: structure was activated and later deactivated
+
+- **Name**: name of the tier structure  
+- **Type**: points logic used (for example Point balance, Points earned)  
+- **Expiration**: selected tier expiration model or **No expiration**  
+- **Downgrade**: downgrade behavior (for example No downgrade, Single-level, Multi-level)  
+- **Tier levels**: number of defined tiers  
+- **Loyalty programs**: programs where the structure is assigned  
+
+Some values may include warning-style labels when the configuration requires attention.
+
+Use the **⋮** menu on the right to edit or delete a tier structure.
+
+### Structure details
+
+Select a structure name to open a read-only summary.
+
+From this view, you can activate or deactivate the structure.
+
+The details view includes:
+- General settings  
+- Tier levels  
+- Tier expiration  
+- Tier downgrade   
+
+## Using tier structures in campaigns
+
+Use tier structures in the program Designer to define how customers are grouped into tiers.
+
+### Adding a tier structure
+
+Add a tier structure from the **Building Blocks** panel.
+
+<Note>
+You can assign only one tier structure to a campaign.
+</Note>
+
+1. Open the **program Designer**
+2. In the **Building Blocks** panel, locate **Tier structures**
+3. If needed, activate a structure
+4. Use the **Quick assign** icon to add the structure to the campaign
+
+<Note>
+Only **active** tier structures can be added.
+</Note>
+
+### How it appears in the campaign
+
+After assignment:
+
+- The structure appears in the **Wallets** section
+- Tier levels are shown within the wallet view
+
+<Note>
+If you deactivate an assigned tier structure, it remains assigned to the campaign but becomes inactive.
+</Note>
+
+### Removing a tier structure
+
+Remove tier structures from the **Building Blocks** panel.
+
+<Note>
+You cannot remove a tier structure directly from the **Wallets** section after assignment.
+</Note>

documentation/docs.json

@@ -245,7 +245,8 @@
                   "build/earning-rules",
                   "build/loyalty-points",
                   "build/loyalty-tiers",
-                  "build/loyalty-card-import"
+                  "build/loyalty-card-import",
+                  "build/create-tier-structures"
                 ]
               },
               {