[Discounts] Described Discounts API #2783

mnocon · 2025-06-10T22:04:14Z

This PR describes how you can use the Discounts PHP API and the core concepts needed to work with it.

Previews:

github-actions · 2025-06-10T22:13:47Z

Preview of modified files

Preview of modified Markdown:

mnocon · 2025-06-11T07:00:17Z

code_samples/discounts/src/Command/ManageDiscountsCommand.php

+                new IsInRegions(['germany', 'france']),
+                new IsProductInArray(['product-1', 'product-2']),
+                new IsInCurrency('EUR'),
+                new IsValidDiscountCode($discountCode->getCode(), $discountCode->getUsedLimit()),


TBH I'm not sure about the $discountCode->getUsedLimit() part - which value should be passed here, the current usage or the max usage?

If I understand correctly, the condition calls the resolver which takes a single argument - so the second argument to IsValidDiscountCode is actually not used?

Maybe @Steveb-p can clarify, but to me it's the max usage.

mnocon · 2025-06-11T07:35:50Z

code_samples/discounts/src/Command/ManageDiscountsCommand.php

+        $discountCode = $this->discountCodeService->createDiscountCode($discountCodeCreateStruct);
+
+        $discountCreateStruct = new DiscountCreateStruct();
+        $discountCreateStruct->setIdentifier('discount_identifier')


I've chosen the fluent API usage over the constructor, as this is self-documenting for the code sample - I'd just use the constructor in "standard" code.

I hope it will be clear for the readers that they can just use the constructor.

docs/discounts/discounts_api.md

+## Search
+
+You can search for Discounts using the [`DiscountServiceInterface::findDiscounts()](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html#method_findDiscounts) method. 
+To learn more about the available search options, see Discounts' Search Criteria and Sort Clauses.


konradoboza

Very solid overall 💪 A few remarks from my end:

code_samples/discounts/src/Command/ManageDiscountsCommand.php

konradoboza · 2025-06-11T07:37:40Z

code_samples/discounts/src/Command/ManageDiscountsCommand.php

+                new IsInRegions(['germany', 'france']),
+                new IsProductInArray(['product-1', 'product-2']),
+                new IsInCurrency('EUR'),
+                new IsValidDiscountCode($discountCode->getCode(), $discountCode->getUsedLimit()),


Maybe @Steveb-p can clarify, but to me it's the max usage.

docs/discounts/discounts_api.md

mnocon · 2025-06-11T08:15:28Z

@konradoboza thank you for your suggestions, I've applied them in e141ad2

Please note that I've added a small note on Discount Statuses.

github-actions · 2025-06-11T11:24:52Z

code_samples/ change report

Before (on target branch) After (in current PR)


code_samples/discounts/src/Command/ManageDiscountsCommand.php


code_samples/discounts/src/Command/ManageDiscountsCommand.php

docs/discounts/discounts_api.md@117:``` php hl_lines="60-66 68-92"
docs/discounts/discounts_api.md@118:[[= include_file('code_samples/discounts/src/Command/ManageDiscountsCommand.php') =]]
docs/discounts/discounts_api.md@119:```

001⫶<?php
002⫶
003⫶declare(strict_types=1);
004⫶
005⫶namespace App\Command;
006⫶
007⫶use DateTimeImmutable;
008⫶use Ibexa\Contracts\Core\Collection\ArrayMap;
009⫶use Ibexa\Contracts\Core\Repository\PermissionResolver;
010⫶use Ibexa\Contracts\Core\Repository\UserService;
011⫶use Ibexa\Contracts\Discounts\DiscountServiceInterface;
012⫶use Ibexa\Contracts\Discounts\Value\DiscountType;
013⫶use Ibexa\Contracts\Discounts\Value\Struct\DiscountCreateStruct;
014⫶use Ibexa\Contracts\Discounts\Value\Struct\DiscountTranslationStruct;
015⫶use Ibexa\Contracts\DiscountsCodes\DiscountCodeServiceInterface;
016⫶use Ibexa\Contracts\DiscountsCodes\Value\Struct\DiscountCodeCreateStruct;
017⫶use Ibexa\Discounts\Value\DiscountCondition\IsInCurrency;
018⫶use Ibexa\Discounts\Value\DiscountCondition\IsInRegions;
019⫶use Ibexa\Discounts\Value\DiscountCondition\IsProductInArray;
020⫶use Ibexa\Discounts\Value\DiscountRule\FixedAmount;
021⫶use Ibexa\DiscountsCodes\Value\DiscountCondition\IsValidDiscountCode;
022⫶use Symfony\Component\Console\Command\Command;
023⫶use Symfony\Component\Console\Input\InputInterface;
024⫶use Symfony\Component\Console\Output\OutputInterface;
025⫶
026⫶final class ManageDiscountsCommand extends Command
027⫶{
028⫶    protected static $defaultName = 'discounts:manage';
029⫶
030⫶    private DiscountServiceInterface $discountService;
031⫶
032⫶    private DiscountCodeServiceInterface $discountCodeService;
033⫶
034⫶    private PermissionResolver $permissionResolver;
035⫶
036⫶    private UserService $userService;
037⫶
038⫶    public function __construct(
039⫶        UserService $userSerice,
040⫶        PermissionResolver $permissionResolver,
041⫶        DiscountServiceInterface $discountService,
042⫶        DiscountCodeServiceInterface $discountCodeService
043⫶    ) {
044⫶        $this->userService = $userSerice;
045⫶        $this->discountService = $discountService;
046⫶        $this->discountCodeService = $discountCodeService;
047⫶        $this->permissionResolver = $permissionResolver;
048⫶
049⫶        parent::__construct();
050⫶    }
051⫶
052⫶    protected function execute(InputInterface $input, OutputInterface $output): int
053⫶    {
054⫶        $this->permissionResolver->setCurrentUserReference(
055⫶            $this->userService->loadUserByLogin('admin')
056⫶        );
057⫶
058⫶        $now = new DateTimeImmutable();
059⫶
060❇️        $discountCodeCreateStruct = new DiscountCodeCreateStruct(
061❇️            'summer10',
062❇️            null, // Unlimited usage
063❇️            $this->permissionResolver->getCurrentUserReference()->getUserId(),
064❇️            $now
065❇️        );
066❇️        $discountCode = $this->discountCodeService->createDiscountCode($discountCodeCreateStruct);
067⫶
068❇️        $discountCreateStruct = new DiscountCreateStruct();
069❇️        $discountCreateStruct
070❇️            ->setIdentifier('discount_identifier')
071❇️            ->setType(DiscountType::CART)
072❇️            ->setPriority(10)
073❇️            ->setEnabled(true)
074❇️            ->setUser($this->userService->loadUserByLogin('admin'))
075❇️            ->setRule(new FixedAmount(10))
076❇️            ->setStartDate($now)
077❇️            ->setConditions([
078❇️                new IsInRegions(['germany', 'france']),
079❇️                new IsProductInArray(['product-1', 'product-2']),
080❇️                new IsInCurrency('EUR'),
081❇️                new IsValidDiscountCode($discountCode->getCode(), $discountCode->getUsedLimit()),
082❇️            ])
083❇️            ->setTranslations([
084❇️                new DiscountTranslationStruct('eng-GB', 'Discount name', 'This is a discount description', 'Promotion Label', 'Promotion Description'),
085❇️                new DiscountTranslationStruct('ger-DE', 'Discount name (German)', 'Description (German)', 'Promotion Label (German)', 'Promotion Description (German)'),
086❇️            ])
087❇️            ->setEndDate(null) // Permanent discount
088❇️            ->setCreatedAt($now)
089❇️            ->setUpdatedAt($now)
090❇️            ->setContext(new ArrayMap(['custom_context' => 'custom_value']));
091❇️
092❇️        $this->discountService->createDiscount($discountCreateStruct);
093⫶
094⫶        return Command::SUCCESS;
095⫶    }
096⫶}

Download colorized diff

adriendupuis

I'm lost with expression values and condition Identifiers in REST. Maybe it's only for migration, not REST?

adriendupuis · 2025-06-13T07:58:52Z

docs/discounts/discounts_api.md

+
+For example, you can automatically create a discount when a customer places their 3rd order, encouraging them to make another purchase and increase their chances of becoming a local customer.
+
+You can manage discounts using [data migrations](importing_data.md#discounts), [REST API](/api/rest_api/rest_api_reference/rest_api_reference.html#discounts), or the PHP API by using the [Ibexa\Contracts\Discounts\DiscountServiceInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html) service.


Suggested change

You can manage discounts using [data migrations](importing_data.md#discounts), [REST API](/api/rest_api/rest_api_reference/rest_api_reference.html#discounts), or the PHP API by using the [Ibexa\Contracts\Discounts\DiscountServiceInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html) service.

You can manage discounts using [data migrations](importing_data.md#discounts), [REST API](/api/rest_api/rest_api_reference/rest_api_reference.html#discounts), or the PHP API by using the [`Ibexa\Contracts\Discounts\DiscountServiceInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html) service.

adriendupuis · 2025-06-13T07:59:17Z

docs/discounts/discounts_api.md

+
+When using the PHP API, the discount type defines where the discount can be applied.
+
+Discounts are applied in two places, listed in the [DiscountType](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-DiscountType.html) class:


Suggested change

Discounts are applied in two places, listed in the [DiscountType](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-DiscountType.html) class:

Discounts are applied in two places, listed in the [`DiscountType`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-DiscountType.html) class:

adriendupuis · 2025-06-13T08:20:19Z

docs/discounts/discounts_api.md

+
+To define when a discount activates and how the price is reduced, use rules and conditions.
+They make use of the [Symfony Expression language]([[= symfony_doc=]]//components/expression_language.html).
+Use the expression values provided below when using data migrations or the REST API to pass the right values.


I don't get where and how to use those expression values, especially when looking at REST.

The "Rules" table below has discount_percentage but /api/rest_api/rest_api_reference/rest_api_reference.html#discounts-create-discount use

"rule": { "type": "percentage", "amount": 10 },

The "Conditions" table says for is_in_category that expression value is categories but the REST example uses

"conditions": [ { "class": "Ibexa\\Discounts\\Value\\DiscountCondition\\IsInCategory", "parameters": [["1", "2"]] } ]

It seems a bit more understandable on migration side.
Identifiers (like is_in_currency) and expression values (like currency_code) can be found on https://ez-systems-developer-documentation--2783.com.readthedocs.build/en/2783/content_management/data_migration/importing_data/#discounts example.

You're right, what I had in mind was:
"it might be useful to know the expression values when parsing the REST responses", because they are there.

But they are not needed when using the REST API to create.

Which one would be clearer to you - drop the REST API mention or mention that they are visible in REST responses?

I continue on this while reviewing #2780 and I see that the expression values

are not used in payloads
https://github.com/ibexa/documentation-developer/pull/2780/files#diff-a1cd766b343982e619dde634343b245f76b8eee0fb54043d811d25111bc01d93R8-R27

are used in responses
https://github.com/ibexa/documentation-developer/pull/2780/files#diff-dd6551ebe700fe3eec9bb159b5ba5c5c01aa4efc3b0826d0a862ad24ccafb28cR15-R31

I don't know now how to clarify that yet.
Somehow this confusion is "REST API's fault" which can't be fixed.

@mnocon Lets be just straight.

Suggested change

Use the expression values provided below when using data migrations or the REST API to pass the right values.

Use the expression values provided below when using data migrations or when parsing REST API responses.

adriendupuis · 2025-06-13T08:27:31Z

docs/discounts/discounts_api.md

+| `Ibexa\Discounts\Value\DiscountRule\FixedAmount` | `fixed_amount` | Deducts the specified amount, for example 10 EUR, from the base price | `discount_amount` |
+| `Ibexa\Discounts\Value\DiscountRule\Percentage` | `percentage` | Deducts the specified percentage, for example -10%, from the base price | `discount_percentage` |


Thank you! I was wondering if there's anything I could do to fix this, this is great 🙇

adriendupuis · 2025-06-13T08:28:00Z

docs/discounts/discounts_api.md

+| Promotion label | Information displayed to customers |
+| Promotion description | Information displayed to customers |
+
+Use the [DiscountTranslationStruct](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Struct-DiscountTranslationStruct.html) to provide translations for discounts.


Suggested change

Use the [DiscountTranslationStruct](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Struct-DiscountTranslationStruct.html) to provide translations for discounts.

Use the [`DiscountTranslationStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Struct-DiscountTranslationStruct.html) to provide translations for discounts.

adriendupuis · 2025-06-13T08:44:32Z

docs/discounts/discounts_api.md

+### Priority
+
+You can set discount priority as a number between 1 and 10 to indicate which discount should have [higher priority](discounts_guide.md#discounts-priority) when choosing the one to apply.


It took me some time to find out where this limit is set…:
https://github.com/ibexa/discounts/blob/main/src/bundle/Resources/config/validation.yaml#L18-L20

adriendupuis · 2025-06-13T08:51:37Z

docs/discounts/discounts_api.md

+
+## Search
+
+You can search for Discounts using the [`DiscountServiceInterface::findDiscounts()](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html#method_findDiscounts) method.


Suggested change

You can search for Discounts using the [`DiscountServiceInterface::findDiscounts()](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html#method_findDiscounts) method.

You can search for Discounts using the [`DiscountServiceInterface::findDiscounts()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html#method_findDiscounts) method.

adriendupuis · 2025-06-13T09:07:06Z

docs/discounts/discounts_api.md

+
+- has the highest possible priority value
+- deducts 10 EUR from the base price of the product
+- is permanent


Suggested change

- is permanent

- is [permanent](#start-and-end-date)

adriendupuis · 2025-06-13T09:15:56Z

docs/discounts/discounts_api.md

+The example below contains a Command creating a cart discount. The discount:
+
+- has the highest possible priority value
+- deducts 10 EUR from the base price of the product


Suggested change

- deducts 10 EUR from the base price of the product

- [rule](#rules) a deduction of 10 EUR from the base price of the product

adriendupuis · 2025-06-13T09:20:00Z

docs/discounts/discounts_api.md

+- is valid in Germany and France
+- applies to 2 products
+- requires a `summer10` discount code to be activated. The code can be used unlimited number of times


Suggested change

- is valid in Germany and France

- applies to 2 products

- requires a `summer10` discount code to be activated. The code can be used unlimited number of times

- [depends](#conditions) on

- being bought from Germany or France

- 2 products

- a `summer10` [discount code](#discount-codes) which can be used unlimited number of times

mnocon · 2025-06-13T09:28:53Z

docs/content_management/data_migration/importing_data.md

@@ -522,6 +522,8 @@ The provided conditions overwrite any already existing ones.
 [[= include_file('code_samples/data_migration/examples/discounts/discount_update.yaml') =]]
 ```

+For a list of available conditions, see [Discounts API](discounts_api.md).


Suggested change

For a list of available conditions, see [Discounts API](discounts_api.md).

For a list of available conditions, see [Discounts API](discounts_api.md#conditions).

mnocon changed the base branch from discounts to discounts-rest June 10, 2025 22:11

mnocon force-pushed the discounts-rest branch from 35978c8 to 636c53c Compare June 10, 2025 22:12

mnocon marked this pull request as ready for review June 11, 2025 06:41

mnocon added the Needs DEV review label Jun 11, 2025

mnocon requested review from Steveb-p and konradoboza June 11, 2025 06:41

mnocon commented Jun 11, 2025

View reviewed changes

docs/discounts/discounts_api.md Outdated Show resolved Hide resolved

mnocon commented Jun 11, 2025

View reviewed changes

konradoboza reviewed Jun 11, 2025

View reviewed changes

mnocon force-pushed the discounts-rest branch from 7583a7d to eed2aed Compare June 11, 2025 07:53

mnocon force-pushed the discounts-api branch from bc9b5bd to e141ad2 Compare June 11, 2025 08:13

mnocon requested a review from konradoboza June 11, 2025 08:15

konradoboza approved these changes Jun 11, 2025

View reviewed changes

mnocon added Needs DOC review and removed Needs DEV review labels Jun 11, 2025

mnocon requested a review from a team June 11, 2025 08:26

ezrobot requested review from adriendupuis, dabrt and julitafalcondusza and removed request for a team June 11, 2025 08:26

mnocon force-pushed the discounts-rest branch from eed2aed to 01e4593 Compare June 11, 2025 11:09

mnocon added 2 commits June 11, 2025 13:11

[Discounts] Described Discounts API

9b88c82

Review fixes

0cd5ae4

mnocon force-pushed the discounts-api branch from e141ad2 to 0cd5ae4 Compare June 11, 2025 11:13

adriendupuis reviewed Jun 13, 2025

View reviewed changes

mnocon commented Jun 13, 2025

View reviewed changes


		For example, you can automatically create a discount when a customer places their 3rd order, encouraging them to make another purchase and increase their chances of becoming a local customer.

		You can manage discounts using [data migrations](importing_data.md#discounts), [REST API](/api/rest_api/rest_api_reference/rest_api_reference.html#discounts), or the PHP API by using the [Ibexa\Contracts\Discounts\DiscountServiceInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html) service.


		When using the PHP API, the discount type defines where the discount can be applied.

		Discounts are applied in two places, listed in the [DiscountType](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-DiscountType.html) class:

	Use the expression values provided below when using data migrations or the REST API to pass the right values.
	Use the expression values provided below when using data migrations or when parsing REST API responses.

		\| `Ibexa\Discounts\Value\DiscountRule\FixedAmount` \| `fixed_amount` \| Deducts the specified amount, for example 10 EUR, from the base price \| `discount_amount` \|
		\| `Ibexa\Discounts\Value\DiscountRule\Percentage` \| `percentage` \| Deducts the specified percentage, for example -10%, from the base price \| `discount_percentage` \|

	Use the [DiscountTranslationStruct](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Struct-DiscountTranslationStruct.html) to provide translations for discounts.
	Use the [`DiscountTranslationStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Struct-DiscountTranslationStruct.html) to provide translations for discounts.

		### Priority

		You can set discount priority as a number between 1 and 10 to indicate which discount should have [higher priority](discounts_guide.md#discounts-priority) when choosing the one to apply.


		## Search

		You can search for Discounts using the [`DiscountServiceInterface::findDiscounts()](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountServiceInterface.html#method_findDiscounts) method.

	- deducts 10 EUR from the base price of the product
	- [rule](#rules) a deduction of 10 EUR from the base price of the product

	For a list of available conditions, see [Discounts API](discounts_api.md).
	For a list of available conditions, see [Discounts API](discounts_api.md#conditions).

[Discounts] Described Discounts API #2783

Are you sure you want to change the base?

[Discounts] Described Discounts API #2783

Conversation

mnocon commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jun 10, 2025

Preview of modified files

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mnocon Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

konradoboza left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mnocon commented Jun 11, 2025

Uh oh!

github-actions bot commented Jun 11, 2025

code_samples/ change report

Uh oh!

adriendupuis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mnocon commented Jun 10, 2025 •

edited

Loading

mnocon Jun 11, 2025 •

edited

Loading