voucherifyio · p-woznikowski · Apr 13, 2026 · Apr 13, 2026 · Apr 17, 2026 · Apr 20, 2026
diff --git a/changelog/ARTICLES.md b/changelog/ARTICLES.md
@@ -5,6 +5,10 @@
 
 Older changes in [DEPRECATED.md](deprecated/DEPRECATED.md)
 
+## 2026-07-16
+
+Add info about caching to `checking-eligibility.mdx`.
+
 ## 2026-07-06
 
 - Deleted `team-management.mdx` as it was outdated and duplicated fresh content.

diff --git a/changelog/OPEN-API.md b/changelog/OPEN-API.md
@@ -4,6 +4,14 @@
 
 Older changes in [DEPRECATED.md](deprecated/DEPRECATED.md)
 
+## 2026-07-21
+
+Deprecated all `v1/loyalties` methods
+
+## 2026-07-17
+
+Changed ReadMe callouts to Mintlify ones in the `OpenAPI.json` file.
+
 ## 2026-07-16
 
 Add info about caching to `v1/qualifications` and `/client/v1/qualifications`.

diff --git a/documentation/api-reference/errors.mdx b/documentation/api-reference/errors.mdx
@@ -40,6 +40,7 @@ The Voucherify API uses conventional HTTP status codes to indicate success or fa
 | 406              | Not Acceptable            | The API is unable to produce a response in a format specified by the `Accept` header. In most cases the only available response format is `application/json`.                     |
 | 409              | Duplicated resource found | A resource with similar parameters has been found, so the request couldn't be processed. For example, a request was sent to create a voucher with a name that was already in use. |
 | 415              | Unsupported Media Type    | The API is unable to consume a request in a format specified by the `Content-Type` header.                                                                                        |
+| 423              | Locked                    | The resource exists, but its current state blocks the operation. Loyalty v2 examples include an inactive program (`non_active_program`) or a loyalty card with zero balance (`zero_card_balance`). |
 | 429              | API limit reached         | Error occurs when you exceed your limit of API calls or when your subscription plan has ended.                                                                                    |
 | 500              | Internal Server Error     | An internal API error occurred. Don't worry, we track and verify all such errors and try to react as asap as possible.                                                            |
 
@@ -86,7 +87,10 @@ The table below shows a list of errors that may be returned along with a brief d
 | `missing_order_items`                 | order items were not specified                                                                                                                                                                                                      |
 | `missing_order_items_amount`          | missing order item's amount(s)                                                                                                                                                                                                      |
 | `missing_reward`                      | reward is missing                                                                                                                                                                                                                   |
+| `member_already_exists`               | the customer is already a member of the loyalty v2 program                                                                                                                                                                          |
 | `multiple_requests`                   | multiple requests detected; i.e. when a redemption is in progress and a session lock is in place, then an attempt to validate the voucher will result in this error because it is unknown whether the voucher can or cannot be used |
+| `non_active_program`                  | the loyalty v2 program is not in `ACTIVE` status for an operation that requires an active program                                                                                                                                   |
+| `zero_card_balance`                   | the loyalty card has no points available for a spend operation such as pay with points                                                                                                                                              |
 | `no_voucher_suitable_for_publication` | lack of vouchers suitable for publication                                                                                                                                                                                           |
 | `not_found`                           | resource with given ID/code does not exist                                                                                                                                                                                          |
 | `order_rules_violated`                | order did not match validation rules                                                                                                                                                                                                |

diff --git a/documentation/api-reference/listing.mdx b/documentation/api-reference/listing.mdx
@@ -36,6 +36,32 @@ However, the following list API methods use the `starting_after_id` query parame
 
 The response to these methods may include a `more_starting_after` key that takes a string value with an ID. Use this ID with the `starting_after_id` query parameter to display another page of results.
 
+## Cursor pagination (Loyalty v2)
+
+Loyalty v2 list endpoints use cursor pagination instead of `page` or `starting_after_id`.
+
+Typical response shape:
+
+```json
+{
+  "data": [],
+  "cursor": {
+    "next": "lcrsctx_12989e71c62b6d5baf",
+    "expires_at": "2026-06-18T16:32:07.896Z"
+  },
+  "object": "list"
+}
+```
+
+How to page results:
+
+1. Call the list endpoint without `cursor` to get the first page.
+2. If `cursor.next` is present, call the same endpoint again with `?cursor={cursor.next}`.
+3. Stop when `cursor` is `null` or `cursor.next` is missing.
+4. Treat `cursor.expires_at` as the validity window for that cursor value. Request a new first page if the cursor expires.
+
+Cursor prefixes differ by resource (for example `lcrsctx_` for card transactions and `lcrsmbr_` for members). Always pass the exact `cursor.next` value returned by the previous response. See the Loyalty v2 endpoint pages under API reference for resource-specific cursor patterns.
+
 ## Response format
 
 The listing method returns a dictionary with a data property that contains an array of resources. The maximum number of resources returned is determined by the `limit` query parameter. If no more resources are available, the resulting array on a given page will be empty. The result can be narrowed down according to the specified (or default) filters.

diff --git a/documentation/api-reference/loyalties/introduction-to-legacy-loyalty.mdx b/documentation/api-reference/loyalties/introduction-to-legacy-loyalty.mdx
@@ -0,0 +1,25 @@
+---
+title: "Legacy loyalty API"
+description: "Legacy loyalty API endpoints for managing loyalty campaigns, members, points, tiers, and rewards."
+---
+
+<Warning>
+
+<Badge color="yellow">Legacy loyalty API</Badge>
+
+These endpoints belong to the legacy loyalty API (`/v1/loyalties`).
+
+Voucherify will not develop new features for this API. Critical issues may still receive fixes.
+
+For new integrations, use [Loyalty v2](/build/loyalty-overview).
+
+If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support").
+
+</Warning>
+
+The Loyalties API lets you manage legacy loyalty campaigns and their members, points, earning rules, tiers, and rewards through the `/v1/loyalties` endpoints.
+
+For the current loyalty solution, see:
+- [Loyalty v2 overview](/build/loyalty-overview).
+- the Loyalty v2 section in the API reference.
+- [Integrate loyalty v2](/guides/loyalty-v2-integrate).
diff --git a/documentation/api-reference/validations/validation-object.mdx b/documentation/api-reference/validations/validation-object.mdx
@@ -66,7 +66,8 @@ mode: "frame"
           <code>stacking_rules</code>
           object, all redeemables here will be
           <code>APPLICABLE</code>.
-          Read more in [the Stacking rules article]/orchestrate/stacking-rules.
+          Read more in
+          <a href="/orchestrate/stacking-rules">the Stacking rules article</a>.
         </p>
         Array any of:
         <ol>

diff --git a/documentation/build/create-benefits.mdx b/documentation/build/create-benefits.mdx
@@ -0,0 +1,214 @@
+---
+title: Create benefits
+description: Configure a reusable benefit for loyalty earning rules
+keywords: ['benefits', 'loyalty benefits', 'benefit builder', 'earning rule benefits']
+tag: "NEW"
+---
+
+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**
+- Activate, edit, or delete benefits using the **⋮** actions menu 
+
+## Prerequisites for creating benefits
+
+Before creating a benefit, prepare the resources required for the selected benefit type.
+
+Depending on the benefit type, you may need:
+- A point wallet for point-based benefits.
+- Products or SKUs for material benefits.
+- Gift voucher or discount coupon campaigns for digital benefits.
+- Metadata schemas for metadata-based proportional points.
+- Custom event schemas for metadata values based on custom events.
+
+<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**.
+
+    By the default, the stock checkbox is set to **Unlimited stock**. Uncheck it and enter the **Stock limit**, which defines how many times the benefit can be issued.
+
+    </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 point-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 point wallet directly from the builder using the **+** icon.
+
+    Configure the following fields:
+    - **Point wallet**: Selects the point wallet that receives the points.
+    - **Point value**: Number of points awarded.
+
+    #### 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.
+
+    <AccordionGroup>
+
+        <Accordion title="Order amount calculations">
+
+        Use order amount calculations to award points based on total order values.
+
+        Available order amount calculations:
+        - **Pre-discount order amount**: Uses the total order amount before discounts are applied. Configure **Points** and **Amount**.
+        - **Post-discount order amount**: Uses the total order amount after discounts are applied. Configure **Points** and **Amount**.
+
+        </Accordion>
+
+        <Accordion title="Order item calculations">
+
+        Use order item calculations to award points based on selected order items.
+
+        Use **Applicable to** to select products, SKUs, or product collections included in the calculation. You can create a new product or product collection directly from the builder using the **+** icon.
+
+        Available order item calculations:
+        - **Pre-discount order items amount**: Uses selected order item values before discounts are applied. Configure **Points**, **Amount**, and **Applicable to**.
+        - **Post-discount order items amount**: Uses selected order item values after discounts are applied. Configure **Points**, **Amount**, and **Applicable to**.
+        - **Order items quantity**: Uses the quantity of selected order items. Configure **Points**, **Amount**, and **Applicable to**.
+
+        </Accordion>
+
+        <Accordion title="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.
+
+        Available metadata calculations:
+        - **Customer metadata value**: Uses a selected customer metadata property. Configure **Points**, **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**.
+
+        </Accordion>
+
+    </AccordionGroup>
+
+    </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 voucher campaign** to select a gift voucher campaign.
+
+    In **Balance**, enter the credit balance added to the gift voucher.
+
+    <Note>
+
+    The balance adds credits to the gift voucher. If a new gift voucher is issued as a benefit, the value in **Balance** will be added to the initial value of the gift voucher as defined in the gift card campaign.
+
+    </Note>
+
+    #### Discount coupons
+
+    Use **Discount coupons** to select a discount coupon campaign.
+
+    The benefit will issue a voucher from the selected 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>
+
+Once saved, the benefit is listed in **Benefits** in **Loyalty hub**.
+
+You can select it in the **Benefit** effect when configuring an **earning rule**.