From 8551d9b6f869050fdb553bc9fc974196f6abcff5 Mon Sep 17 00:00:00 2001
From: MaciekVoucherify <130568368+MaciekVoucherify@users.noreply.github.com>
Date: Tue, 2 Jun 2026 17:02:45 +0200
Subject: [PATCH] benefits

---
 documentation/build/create-benefit.mdx | 195 +++++++++++++++++++++++++
 documentation/docs.json                |   3 +-
 2 files changed, 197 insertions(+), 1 deletion(-)
 create mode 100644 documentation/build/create-benefit.mdx

diff --git a/documentation/build/create-benefit.mdx b/documentation/build/create-benefit.mdx
new file mode 100644
index 000000000..349de49c0
--- /dev/null
+++ b/documentation/build/create-benefit.mdx
@@ -0,0 +1,195 @@
+---
+title: Benefit builder
+description: Configure a reusable benefit for loyalty earning rules
+keywords: ['benefits', 'loyalty benefits', 'benefit builder', 'earning rule benefits']
+---
+
+Benefits define rewards that can be awarded through loyalty earning rules.
+
+Go to **Loyalty hub** > **Benefits**.
+
+From the **Benefits** view, you can:
+- view all existing benefits and their status
+- open benefits to review their configuration
+- search benefits using the search bar
+- filter benefits using **Add filter**
+- reload the benefits list using **Reload**
+- create benefits using **+ Create benefit**
+- edit or delete benefits using the contextual actions menu (`⋮`)
+
+## Before you start
+
+Before creating a benefit, prepare the resources required for the selected benefit type.
+
+Depending on the benefit type, you may need:
+- a card definition for points-based benefits
+- products or SKUs for material benefits
+- gift voucher or discount coupon campaigns for digital benefits
+- metadata schemas for metadata-based proportional points
+
+<Note>
+
+Some resources can be created directly from the builder using the **+** icon. SKUs, gift voucher campaigns, and discount coupon campaigns cannot be created from the benefit builder.
+
+</Note>
+
+## Create a benefit
+
+Benefits are configured in a multi-step builder.
+
+You can use **Save draft** and complete the configuration later.
+
+Go to **Loyalty hub** > **Benefits** and use **+ Create benefit**.
+
+<Steps>
+
+<Step>
+
+## General settings
+
+Configure the benefit name and stock.
+
+Enter the benefit name in **Name benefit**.
+
+In **Stock quantity**, enter how many times the benefit can be issued.
+
+The maximum supported value for **Stock quantity** is `100000000`.
+
+</Step>
+
+<Step>
+
+## Configuration
+
+Select the benefit type and configure its details.
+
+Supported benefit types:
+- **Points**
+- **Material**
+- **Digital**
+
+<Tabs>
+
+<Tab title="Points">
+
+Use **Points** to create a points-based benefit.
+
+In **Points configuration**, select how points are awarded.
+
+### Fixed points
+
+Use **Fixed** to award the same number of points each time the benefit is applied.
+
+You can create a new wallet directly from the builder using the **+** icon.
+
+Configure the following fields:
+- **Card definition**: selects the wallet that receives the points
+- **Points value**: number of points awarded
+
+The maximum supported value for **Points value** is `100000000`.
+
+### Proportional points
+
+Use **Proportional** to calculate points from order values, item quantities, or metadata values.
+
+Configure the following fields:
+- **Calculation type**: defines the value used to calculate points
+- **Card definition**: selects the wallet that receives the points
+- **Points**: number of points awarded for the selected value
+
+Calculation methods are grouped by type.
+
+**Order amount calculations**
+
+Use order amount calculations to award points based on total order values.
+
+- **Pre-discount order amount**: uses the total order amount before discounts are applied. Configure **Amount**.
+- **Post-discount order amount**: uses the total order amount after discounts are applied. Configure **Amount**.
+
+**Order item calculations**
+
+Use order item calculations to award points based on selected order items.
+
+Use **Applicable to** to select products or product collections included in the calculation. You can create a new product or product collection directly from the builder using the **+** icon.
+
+- **Pre-discount order items amount**: uses selected order item values before discounts are applied. Configure **Amount** and **Applicable to**.
+- **Post-discount order items amount**: uses selected order item values after discounts are applied. Configure **Amount** and **Applicable to**.
+- **Order items quantity**: uses the quantity of selected order items. Configure **Quantity** and **Applicable to**.
+
+**Metadata calculations**
+
+Use metadata calculations to award points based on metadata values.
+
+You can create a new metadata property directly from the builder using the **+** icon.
+
+- **Customer metadata value**: uses a selected customer metadata property. Configure **Value** and **Metadata property**.
+- **Order metadata value**: uses a selected order metadata property. Configure **Value** and **Metadata property**.
+- **Custom event metadata value**: uses a selected custom event metadata property. Configure **Value** and **Metadata property**.
+
+</Tab>
+
+<Tab title="Material">
+
+Use **Material** to create a benefit based on a product or SKU.
+
+In **Material configuration**, select the source item.
+
+### Product
+
+Use **Product** to select one product as the benefit.
+
+You can create a new product directly from the builder using the **+** icon.
+
+### SKU
+
+Use **SKU** to select a specific product variant as the benefit.
+
+SKUs cannot be created from the benefit builder.
+
+</Tab>
+
+<Tab title="Digital">
+
+Use **Digital** to create a benefit based on an existing voucher campaign.
+
+In **Digital configuration**, select the voucher type.
+
+### Gift vouchers
+
+Use **Gift vouchers** to select a gift voucher campaign.
+
+In **Balance**, enter the balance added to the gift voucher.
+
+The maximum supported value for **Balance** is `100000000`.
+
+### Discount coupons
+
+Use **Discount coupons** to select a discount coupon campaign.
+
+</Tab>
+
+</Tabs>
+
+</Step>
+
+<Step>
+
+## Summary
+
+Review the benefit configuration before saving.
+
+The summary page displays all configured sections:
+- General settings
+- Configuration
+
+Use **Go to step** to return to a selected section and make changes before saving the benefit.
+
+After reviewing the configuration:
+- use **Save draft** to save the benefit without activating it
+- use **Save** to create and activate the benefit
+
+</Step>
+
+</Steps>
+
+After creating a benefit, you can select it in the **Incentive** effect when configuring an earning rule.
\ No newline at end of file
diff --git a/documentation/docs.json b/documentation/docs.json
index 179562614..db5b497f6 100644
--- a/documentation/docs.json
+++ b/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/create-benefit"
                 ]
               },
               {