Skip to content
  • Documentation >
  • Discounts >
  • Discounts API

Discounts API

Manage discounts and discount codes

By integrating with the Discount feature you can automate the process of managing discounts, streamlining the whole process and automating business rules.

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, REST API, or the PHP API by using the Ibexa\Contracts\Discounts\DiscountServiceInterface service.

The core concepts when working with discounts through the APIs are listed below.

Types

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 class:

  • Product catalog - catalog discounts are activated when browsing the product catalog and do not require any action from the customer to be activated
  • Cart - cart discounts can activate when entering the cart, if the right conditions are met. They may also require entering a discount code to be activated

Regardless of activation place, discounts always apply to products and reduce their base price.

To define when a discount activates and how the price is reduced, use rules and conditions. They make use of the Symfony Expression language. Use the expression values provided below when using data migrations or when parsing REST API responses.

Rules

Discount rules define how the calculate the price reduction. The following discount rule types are available:

Rule type Identifier Description Expression value
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

Only a single discount can be applied to a given product, and a discount can only have a single rule.

Conditions

With conditions you can narrow down the scenarios in which the discount applies. The following conditions are available:

Condition Applies to Identifier Description Expression values
Ibexa\Discounts\Value\DiscountCondition\IsInCategory Cart, Catalog is_in_category Checks if the product belongs to specified product categories categories
Ibexa\Discounts\Value\DiscountCondition\IsInCurrency Cart, Catalog is_in_currency Checks if the product has price in the specified currency currency_code
Ibexa\Discounts\Value\DiscountCondition\IsInRegions Cart, Catalog is_in_regions Checks if the customer is making the purchase in one of the specified regions regions
Ibexa\Discounts\Value\DiscountCondition\IsProductInArray Cart, Catalog is_product_in_array Checks if the product belongs to the group of selected products product_codes
Ibexa\Discounts\Value\DiscountCondition\IsUserInCustomerGroup Cart, Catalog is_user_in_customer_group Check if the customer belongs to specified customer groups customer_groups
Ibexa\Discounts\Value\DiscountCondition\IsProductInQuantityInCart Cart is_product_in_quantity_in_cart Checks if the required minimum quantity of a given product is present in the cart quantity
Ibexa\Discounts\Value\DiscountCondition\MinimumPurchaseAmount Cart minimum_purchase_amount Checks if purchase amount in the cart exceeds the specified minimum minimum_purchase_amount
Ibexa\DiscountsCodes\Value\DiscountCondition\IsValidDiscountCode Cart is_valid_discount_code Checks if the correct discount code has been provided and how many times it was used by the customer discount_code, usage_count

When multiple conditions are specified, all of them must be met.

Priority

You can set discount priority as a number between 1 and 10 to indicate which discount should have higher priority when choosing the one to apply.

Start and end date

Discounts can be permanent, or valid only in a specified time frame.

Every discount has a start date, which defaults to the date when the discount was created. The end date can be set to null to make the discount permanent.

Status

You can disable a discount anytime to stop it from being active, even if the conditions enforced by start and end date are met.

Only disabled discounts can be deleted.

Discount translations

The discount has four properties that can be translated:

Property Usage
Name Internal information for store managers
Description Internal information for store managers
Promotion label Information displayed to customers
Promotion description Information displayed to customers

Use the DiscountTranslationStruct to provide translations for discounts.

Discount codes

To activate a cart discount only after a proper discount code is provided, you need to:

  1. Create a discount code using the DiscountCodeServiceInterface::createDiscountCode() method
  2. Attach it to a discount by using the IsValidDiscountCode condition

Set the usedLimit property to the number of times a single customer can use this code, or to null to make the usage unlimited.

The DiscountCodeServiceInterface::registerUsage() method is used to track the number of times a discount code has been used.

Example API usage

The example below contains a Command creating a cart discount. The discount:

  • has the highest possible priority value
  • rule deducts 10 EUR from the base price of the product
  • is permanent
  • depends on
    • being bought from Germany or France
    • 2 products
    • a summer10 discount code which can be used unlimited number of times
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<?php

declare(strict_types=1);

namespace App\Command;

use DateTimeImmutable;
use Ibexa\Contracts\Core\Collection\ArrayMap;
use Ibexa\Contracts\Core\Repository\PermissionResolver;
use Ibexa\Contracts\Core\Repository\UserService;
use Ibexa\Contracts\Discounts\DiscountServiceInterface;
use Ibexa\Contracts\Discounts\Value\DiscountType;
use Ibexa\Contracts\Discounts\Value\Struct\DiscountCreateStruct;
use Ibexa\Contracts\Discounts\Value\Struct\DiscountTranslationStruct;
use Ibexa\Contracts\DiscountsCodes\DiscountCodeServiceInterface;
use Ibexa\Contracts\DiscountsCodes\Value\Struct\DiscountCodeCreateStruct;
use Ibexa\Discounts\Value\DiscountCondition\IsInCurrency;
use Ibexa\Discounts\Value\DiscountCondition\IsInRegions;
use Ibexa\Discounts\Value\DiscountCondition\IsProductInArray;
use Ibexa\Discounts\Value\DiscountRule\FixedAmount;
use Ibexa\DiscountsCodes\Value\DiscountCondition\IsValidDiscountCode;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

final class ManageDiscountsCommand extends Command
{
    protected static $defaultName = 'discounts:manage';

    private DiscountServiceInterface $discountService;

    private DiscountCodeServiceInterface $discountCodeService;

    private PermissionResolver $permissionResolver;

    private UserService $userService;

    public function __construct(
        UserService $userSerice,
        PermissionResolver $permissionResolver,
        DiscountServiceInterface $discountService,
        DiscountCodeServiceInterface $discountCodeService
    ) {
        $this->userService = $userSerice;
        $this->discountService = $discountService;
        $this->discountCodeService = $discountCodeService;
        $this->permissionResolver = $permissionResolver;

        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $this->permissionResolver->setCurrentUserReference(
            $this->userService->loadUserByLogin('admin')
        );

        $now = new DateTimeImmutable();

        $discountCodeCreateStruct = new DiscountCodeCreateStruct(
            'summer10',
            null, // Unlimited usage
            $this->permissionResolver->getCurrentUserReference()->getUserId(),
            $now
        );
        $discountCode = $this->discountCodeService->createDiscountCode($discountCodeCreateStruct);

        $discountCreateStruct = new DiscountCreateStruct();
        $discountCreateStruct
            ->setIdentifier('discount_identifier')
            ->setType(DiscountType::CART)
            ->setPriority(10)
            ->setEnabled(true)
            ->setUser($this->userService->loadUserByLogin('admin'))
            ->setRule(new FixedAmount(10))
            ->setStartDate($now)
            ->setConditions([
                new IsInRegions(['germany', 'france']),
                new IsProductInArray(['product-1', 'product-2']),
                new IsInCurrency('EUR'),
                new IsValidDiscountCode($discountCode->getCode(), $discountCode->getUsedLimit()),
            ])
            ->setTranslations([
                new DiscountTranslationStruct('eng-GB', 'Discount name', 'This is a discount description', 'Promotion Label', 'Promotion Description'),
                new DiscountTranslationStruct('ger-DE', 'Discount name (German)', 'Description (German)', 'Promotion Label (German)', 'Promotion Description (German)'),
            ])
            ->setEndDate(null) // Permanent discount
            ->setCreatedAt($now)
            ->setUpdatedAt($now)
            ->setContext(new ArrayMap(['custom_context' => 'custom_value']));

        $this->discountService->createDiscount($discountCreateStruct);

        return Command::SUCCESS;
    }
}

Similarly, use the deleteDiscount, deleteTranslation, disableDiscount, enableDiscount, and updateDiscount methods from the DiscountServiceInterface to manage the discounts. You can always attach additional logic to the Discounts API by listening to the available events.

You can search for Discounts using the DiscountServiceInterface::findDiscounts() method. To learn more about the available search options, see Discounts' Search Criteria and Sort Clauses.

For discount codes, you can query the database for discount code usage using DiscountCodeServiceInterface::findCodeUsages() and DiscountCodeUsageQuery.