IBX-9683: Document Discounts

docs/discounts/discounts.md

@@ -0,0 +1,17 @@
+---
+description: Discounts help store managers reduce prices on products or product categories.
+page_type: landing_page
+month_change: true
+---
+
+# Discounts
+
+With the Discounts feature, store managers can reduce prices on specific products or categories for all or selected customers.
+After you install it, temporary or permanent discounts can be applied against items from the product catalog or cart.
+
+You can also extend the feature by creating custom pricing rules, application conditions, changing discount priorities,and so on.
+
+[[= cards([
+"discounts/discounts_guide",
+"discounts/install_discounts"
+], columns=4) =]]

docs/discounts/discounts_guide.md

@@ -0,0 +1,102 @@
+---
+description: Discounts LTS Update enables reducing prices on products or product categories based on a detailed logic resolution.
+month_change: false
+---
+
+# Discounts product guide
+
+## What are Discounts
+
+Just like brick-and-mortar shops, online stores use clever strategies to attract new customers, keep loyal ones, boost sales, highlight special products, and clear out inventory.
+
+One powerful technique that helps achieve these goals is offering discounts.
+Discounts allow online stores to temporarily or permanently reduce prices on specific products or categories, making deals more attractive to potential buyers.
+They can be used to encourage first-time purchases, reward loyal customers, promote new or slow-moving items, or drive sales during seasonal events.
+By displaying discounted prices clearly in the catalog or cart, businesses can create a sense of urgency, increase customer satisfaction, and ultimately boost revenue.
+
+[[= product_name =]] can be equipped with the Discounts [LTS update](ibexa_dxp_v4.6.md#lts-updates), that introduces a highly extensible solution for building discounts.
+
+Store managers can apply general discounts for products from the product catalogue or specific discounts for products in the customer's shopping cart.
+Once the target is selected, they can set the type of discount by choosing a discount calculation rule.
+Then they can use an extended set of conditions to decide when their discounts are applied.
+
+Out of the box, the Discounts module delivers three types of discounts:
+
+- "Fixed amount" - where a specified amount of money, for example, 5 Euro, is deducted from the base price
+- "Percentage" - where a specified percentage, for example, 10%, is used to calculate the deducted amount
+- "Buy X, get Y" - where customers purchase a specified number of items (X) and receive additional items (Y) for free or at a discounted price
+
+A selection of conditions used to limit the applicability of a discount is broader, and includes, for example, rules that check whether:
+
+- the product belongs to a specific category
+- the customer belongs to a specific customer group
+- the purchase is made within a defined timeframe
+- a minimum purchase amount is met
+
+!!! note "Difference between discounts and price rules"
+
+    Unlike flexible and highly configurable discounts, [prices applied to customer groups](prices.md#custom-pricing) cannot have time limits, only apply to specific customer groups, and do not offer flexibility to adjust prices at cart level.
+
+You can extend the solution's capabilities beyond the default setup by ...
+
+## Availability
+
+Discounts are an opt-in capability available as an [LTS update](editions.md#lts-updates) starting with the v4.6.XX version of [[= product_name =]], regardless of its edition.
+To begin using Discounts, you must first [install the required packages and perform initial configuration](install_discounts.md).
+
+## How it works
+
+Discounts LTS update relies on an extensible AI framework, which is responsible for gathering information from various sources, such as Discount types, Discount configurations, and contextual details like SiteAccess, user details, locale settings, and more.
+This data can then be combined with user input.
+It's then passed to a service for final processing on [[= product_name =]] side.
+...
+
+### Core concepts
+
+#### Promotion
+
+Promotions are a marketing tool used to increase sales of certain products or product lines.
+They enable sellers to apply various discounts to their stock, generate personalized discount coupons, and can follow strategic promotion schedules.
+
+#### Discount
+
+A a reduction in the usual price, a deduction applied to an online purchase, typically implemented as part of a marketing campaign.
+Discounts can apply to specific items, shipping costs, total order amount and so on.
+
+- Automatic discounts
+
+...
+
+- Discount codes (aka. coupons)
+
+...
+
+### 
+
+## Capabilities
+
+### Management
+
+Users with the appropriate permissions, governed by role-based [policies](policies.md#disc ounts), can control the lifecycle of Discounts by creating, editing, executing, and deleting them.
+Additionally, Discount configurations can be enabled or disabled depending on the organization's needs.
+
+![Discount management screen](img/discount_list.png)
+
+An intuitive Discounts interface displays a list of all available Discounts.
+Here, you can search for specific discounts and filter them by type or status.
+By accessing the detailed view of individual Discounts, you can quickly review all their parameters.
+
+### Extensibility
+
+Built-in Discount types offer a good starting point, but the real power of the Discounts lies in extensibility.
+Extending Discounts opens up new possibilities for building promotional campaigns that help move stock and attach customers.
+...
+
+For example, [[= product_name =]] could apply a special discount when a customer places their 1st, 10th, or 100th order in the storefront.
+This would encourages first-time purchases, repeat business, and long-term customer loyalty. 
+
+## Use cases
+
+Out of the box, the [[= product_name_base =]] Discounts LTS update comes with multiple discount types that can be applied in the following use cases.
+
+### ...

docs/discounts/extend_discounts.md

@@ -0,0 +1,8 @@
+---
+description: Extend Discounts by adding new capabilities.
+month_change: false
+---
+
+# Extend Discounts
+
+By extending [Discounts](discounts_guide.md), you can ...

docs/discounts/install_discounts.md

@@ -0,0 +1,44 @@
+---
+description: Install the Discounts LTS update.
+month_change: false
+---
+
+# Install Discounts
+
+Discounts are available as an LTS update to [[= product_name =]] Commerce, starting with version v4.6.18 or higher.
+To use this feature you must first install the packages and configure them.
+
+## Install packages
+
+Run the following commands to install the packages:
+
+``` bash
+composer require ibexa/discounts
+composer require ibexa/discount-codes
+```
+
+These commands add the feature code, service handlers, helper Twig templates, and configurations required for using Discounts.
+It also modifies the permission system to account for the new functionality.
+
+## Configure Discounts
+
+Once the packages are installed, before you can start using Discounts, you must enable them by following these instructions.
+
+### Modify the database schema
+
+Run the following command, where `<database_name>` is the same name that you defined when you [installed [[= product_name =]]](../getting_started/install_ibexa_dxp.md#change-installation-parameters).
+
+=== "MySQL"
+
+    ```bash
+
+    ```
+
+=== "PostgreSQL"
+
+    ```bash
+    ```
+
+This command modifies the existing database schema by adding database configuration required for using Discounts.
+
+You can now restart you application and start [working with the Discounts feature]([[= user_doc =]]/discounts/work_with_discounts/).

docs/permissions/limitation_reference.md

@@ -41,9 +41,9 @@ The `ActivityLogOwner` limitation specifies if a user can see only their own [re
 |-------|-----------------|--------------------------------------------------------------|
 | `1`   | "Only own logs" | Current user can only access their own activity log entries. |
 
-## CartOwner limitation
+## Cart Owner limitation
 
-The `CartOwner` limitation specifies whether the user can modify a cart.
+The Cart Owner `CartOwner` limitation specifies whether the user can modify a cart.
 
 ### Possible values
 
@@ -62,6 +62,16 @@ The Change Owner (`ChangeOwner`) limitation specifies whether the user can chang
 |------|------|------|
 |`1`|"Forbid"|The user cannot change owner of a content item|
 
+## Discount Owner limitation
+
+The Discount Owner `DiscountOwner` limitation specifies whether the user can interact with a discount.
+
+### Possible values
+
+|Value|UI value|Description|
+|------|------|------|
+|"self"|"self"|Only the user who is the owner of the discount gets access.|
+
 ## Content type Group limitation
 
 The Content Type Group (`UserGroup`) limitation specifies that only users with at least one common *direct* user group with the owner of content get the selected access right.

docs/permissions/permission_use_cases.md

@@ -269,6 +269,20 @@ Set the following permissions to decide what actions are available when users in
 - `checkout/update` - to allow users to modify existing information, for example item quantity
 - `checkout/delete` - to delete checkout
 
+### Discount management
+
+Set the following permissions to decide what actions are available when users interact with discounts:
+
+- `discount/create` - to allow the user to create a new discount
+- `discount/update` - to allow the user to change the parameters of an existing discount
+- `discount/view` - to allow the user to view discounts
+- `discount/delete` - to delete an existing discount
+- `discount/enable` - to allow the user to enable an existing discount
+- `discount/disable` - to allow the user to disable an existing discount
+
+To further control access to a discount, you can use the `DiscountOwner` limitation and set its value to `self`.
+This way users can only interact with their own discounts.
+
 ### Order management
 
 Set the following permissions to decide what actions are available when users interact with orders:

docs/permissions/policies.md

@@ -124,6 +124,17 @@ Each role you assign to user or user group consists of policies which define, wh
 | <nobr>`commerce`</nobr> | <nobr>`currency`</nobr> | manage currencies |
 |                         | <nobr>`region`</nobr>   | manage regions    |
 
+#### Discounts [[% include 'snippets/commerce_badge.md' %]]
+
+| Module               | Function                 | Effect                      | Possible limitations                                         |
+|----------------------|--------------------------|-----------------------------|----------------------------------------------------|
+| <nobr>`discount`</nobr> | <nobr>`create`</nobr> | create a discount           | [DiscountOwner](limitation_reference.md#discount-owner-limitation) |
+|                      | <nobr>`delete`</nobr>    | delete a discount           | [DiscountOwner](limitation_reference.md#discount-owner-limitation) |
+|                      | <nobr>`enable`</nobr>    | enable a discount           | [DiscountOwner](limitation_reference.md#discount-owner-limitation) |
+|                      | <nobr>`disable`</nobr>   | disable a discount          | [DiscountOwner](limitation_reference.md#discount-owner-limitation) |
+|                      | <nobr>`update`</nobr>    | modify discount parameters  | [DiscountOwner](limitation_reference.md#discount-owner-limitation) |
+|                      | <nobr>`view`</nobr>      | view discounts              | [DiscountOwner](limitation_reference.md#discount-owner-limitation) |
+
 #### Orders [[% include 'snippets/commerce_badge.md' %]]
 
 | Module               | Function              | Effect                    | Possible limitations                                         |

docs/search/criteria_reference/discount_created_criterion.md

@@ -0,0 +1,25 @@
+---
+description: Discount CreatedAt Search Criterion
+edition: commerce
+---
+
+# Discount CreatedAt Criterion
+
+The `CreatedAtCriterion` Search Criterion searches for discounts based on the date when they were created.
+
+## Arguments
+
+- `createdAt` - date to be matched, provided as a `DateTimeInterface` object
+- `operator` - optional operator string (EQ, GT, GTE, LT, LTE)
+
+## Example
+
+### PHP
+
+``` php
+$criteria = new \Ibexa\Contracts\Discounts\Value\Query\Criterion\CreatedAtCriterion(
+    new DateTime('2025-04-11 14:07:02'), Operator::GTE
+);
+
+$discountQuery = new DiscountQuery($criteria);
+```

docs/search/criteria_reference/discount_creator_criterion.md

@@ -0,0 +1,24 @@
+---
+description: Discount CreatorCriterion Search Criterion
+edition: commerce
+---
+
+# Creator Criterion
+
+The `CreatorCriterion` Criterion searches for discounts based on the user reference.
+
+## Arguments
+
+- `UserReference` object - \Ibexa\Contracts\Core\Repository\Values\User\UserReference(int $userId)
+
+## Example
+
+### PHP
+
+``` php
+$query = new DiscountQuery(
+    new \Ibexa\Contracts\Discounts\Value\Query\Criterion\CreatorCriterion(
+        \Ibexa\Core\Repository\Values\User\UserReference(14)
+    )
+);
+```

docs/search/criteria_reference/discount_enddate_criterion.md

@@ -0,0 +1,30 @@
+---
+description: Discount EndDate Search Criterion
+edition: commerce
+---
+
+# Discount EndDate Criterion
+
+The `EndDateCriterion` Search Criterion searches for discounts based on the date and time when they expire.
+
+## Arguments
+
+- `value` - searched value provided as the [DateTimeImmutable](https://www.php.net/manual/en/class.datetimeimmutable.php) object
+- `operator` - optional operator string (EQ, GT, GTE, LT, LTE)
+
+## Example
+
+### PHP
+
+``` php
+$criteria = new \Ibexa\Contracts\Discounts\Value\Query\Criterion\LogicalAnd(
+    new \Ibexa\Contracts\Discounts\Value\Query\Criterion\StartDateCriterion(
+        new DateTimeImmutable('2025-04-11 14:07:03'), Operator::GTE
+    ),
+    new \Ibexa\Contracts\Discounts\Value\Query\Criterion\EndDateCriterion(
+        new DateTimeImmutable('2027-04-11 14:07:02'), Operator::LTE
+    ),
+);
+
+$discountQuery = new DiscountQuery($criteria);
+```

docs/search/criteria_reference/discount_identifier_criterion.md

@@ -0,0 +1,22 @@
+---
+description: Discount Identifier Search Criterion
+edition: commerce
+---
+
+# Discount Identifier Criterion
+
+The `Identifier` Search Criterion searches for discounts based on the discount identifier.
+
+## Arguments
+
+- `identifier` - string that represents the discount identifier
+
+## Example
+
+### PHP
+
+``` php
+$criteria = new \Ibexa\Contracts\Discounts\Value\Query\Criterion\IdentifierCriterion('summer-sale');
+
+$discountQuery = new DiscountQuery($criteria);
+```

docs/search/criteria_reference/discount_isenabled_criterion.md

@@ -0,0 +1,22 @@
+---
+description: Discount IsEnabled Search Criterion
+edition: commerce
+---
+
+# Discount IsEnabled Criterion
+
+The `IsEnabledCriterion` Search Criterion searches for discounts based on whether the discount is enabled or not.
+
+## Arguments
+
+- `value` - Boolean value stating whether the discount is enabled or not
+
+## Example
+
+### PHP
+
+``` php
+$criteria = new \Ibexa\Contracts\Discounts\Value\Query\Criterion\IsEnabledCriterion(true);
+
+$discountQuery = new DiscountQuery($criteria);
+```