Introduction
The module’s integration lets you predefine certain promotions for your products.
Development
Core
Entity Definitions
The definitions in this module have id discriminators in the range 220-250. |
The PromotionableSiteEntityDefinition adds the promotionable features to the SiteEntityDefinition. The SiteEntityDefinition
, in its turn, inherits the AbstractEntityDefinition and the AbstractDescriptionableEntityDefinition:

The defined property here is promotionGroup. It’s designed so that it holds the promotions (PromotionGroupEntityDefinition
) for the site.
The PromotionEntityDefinition extends the AbstractEntityDefinition , the AbstractActivatableEntityDefinition and the AbstractFilterableEntityDefinition:

This is the base entity definition for all promotions. Via the respective getter-setter pairs, the following information can be retrieved/stored in the database:
Property | Description |
---|---|
priority |
stores the priority of the promotion. Keep in mind that promotions with lower priority are evaluated before promotions with higher priority |
triggeredMessage |
stores the message that is presented to the customer once the promotion is triggered |
potentialMessage |
stores the message that is presented to the customer once the promotions is in potential state |
description |
stores the description of the promotion |
promotionGroups |
stores the promotion group the particular promotion belongs to |
rule |
stores the rule for the promotion |
The PromotionGroupEntityDefinition extends the AbstractEntityDefinition :

The only defined property here is promotions. It stores a set of promotions (PromotionEntityDefinition
) the defined group consists of.
The PromotionResultEntityDefinition extends the AbstractEntityDefinition , the AbstractPurchasableEntryEntityDefinition and the AbstractPurchasableEntityDefinition:

Via the respective getter-setter pairs, the following information can be retrieved/stored in the database:
Property | Description |
---|---|
description |
stores the description of the promotion result |
promotion |
stores the promotion this promotion is result of |
type |
stores the type of the promotion result - either fired, or potential |
The PromotionResultTypeDefinition extends the AbstractEntityEnum, going further to the MixInEnum:

As an enumerated list, here are stored the values, corresponding to the types of promotion results. The type of the PromotionResultEntityDefinition
could be either FIRED
or POTENTIAL
.
Order-related Entity Definitions
The OrderPromotionEntityDefinition is a base class for all order promotions. It extends the PromotionEntityDefinition, going further to the AbstractEntityDefinition , the AbstractActivatableEntityDefinition and the AbstractFilterableEntityDefinition:

Via the respective getter-setter pairs, the following information can be retrieved/stored in the database:
Property | Description |
---|---|
activeSubtotalThreshold |
stores the subtotal threshold beyond which the promotion gets activated |
potentialSubtotalThreshold |
stores the subtotal threshold beyond which the promotion is considered potential |
The OrderThresholdChangeDeliveryModePromotionEntityDefinition extends the OrderPromotionEntityDefinition:

The delivery mode of the purchase gets changed once the specified threshold is exceeded. For example - if you want a free next-day delivery, you need to buy something for more than 50 EUR. The information for the changed mode is stored in the deliveryMode field.
The OrderThresholdFixedDiscountPromotionEntityDefinition extends the OrderPromotionEntityDefinition and the AbstractExpensableEntityDefinition :

This type of promotion is fired when the client purchases above the given threshold. Then they receive a fixed-value discount. For example - buy something for more than 50 EUR and receive a 5% discount.
The OrderThresholdFreeGiftPromotionEntityDefinition extends the OrderPromotionEntityDefinition:

The promotion is fired when the client purchases above the specified threshold. Then they receive a free gift in their order. For example - buy something for more than 50 EUR and you will receive a free pair of shorts.
Via the respective getter-setter pairs, the following information can be retrieved/stored in the database:
Property | Description |
---|---|
product |
stores the product that we add as a free gift |
quantity |
stores the quantity for the product that we add as a free gift |
The OrderThresholdFreeVoucherPromotionEntityDefinition extends the OrderPromotionEntityDefinition

The promotion is fired when the client purchases above the specified threshold. Then they receive a free voucher. For example - buy something for more than 50 EUR and you will receive a free voucher for 5 EUR.
The OrderThresholdPerfectPartnerPromotionEntityDefinition extends the OrderPromotionEntityDefinition:

The promotion is fired when the client purchases above the specified threshold. Then they receive a given product at a special price. For example - buy something for more than 50 EUR and get any T-shirt for 5 EUR.
The PromotionableAbstractOrderEntityDefinition extends the AbstractOrderEntityDefinition and the AbstractEntityDefinition :

The PromotionableAbstractOrderEntityDefinition
adds some promotion-related attributes to the extended interfaces. The defined property here is promotionResults. It’s designed to store a list of PromotionResultEntityDefinition
-s for the particular order.
The PromotionableAbstractOrderEntryEntityDefinition extends the CartEntryEntityDefinition, going further to the AbstractEntityDefinition and the AbstractPurchasableEntityDefinition:

The PromotionableAbstractOrderEntryEntityDefinition
adds some promotion-related attributes to the extended interfaces. Via the respective getter-setter pairs, the following information can be retrieved/stored in the database:
Property | Description |
---|---|
free |
stores information if the product is free |
freeQuantity |
stores the quantity of the free product |
promotion |
stores the promotion for the discount. |
The PromotionDeliveryModeEntityDefinition extends the DeliveryModeEntityDefinition and the AbstractExpensableEntityDefinition, relying further on the AbstractEntityDefinition , the AbstractActivatableEntityDefinition, the AbstractNameableEntityDefinition and the AbstractDescriptionableEntityDefinition:

The PromotionDeliveryModeEntityDefinition
defines the promotion delivery mode for the DeliveryModeEntityDefinition
. The only property, defined here, is net. It stores information if the delivery mode is net or not.
Price-related Entity Definitions
The PromotionableDiscountEntityDefinition extends the DiscountEntityDefinition, going further to the AbstractEntityDefinition , the AbstractActivatableEntityDefinition, the AbstractExpensableEntityDefinition, the AbstractCatalogableEntityDefinition and the AbstractPurchasableEntityDefinition:

The PromotionableDiscountEntityDefinition
adds the promotion attributes to the extended interfaces. The defined property is promotion - it stores the promotion for the discount.
The PromotionablePriceEntityDefinition extends the PriceEntityDefinition, going further to the AbstractEntityDefinition , the AbstractCatalogableEntityDefinition and the AbstractExpensableEntityDefinition:

The only defined property here - promotion - stores the promotion for the discount.
Product-related Entity Definitions
The ProductBOGOFPromotionEntityDefinition extends the ProductPromotionEntityDefinition, going further to the PromotionEntityDefinition, the AbstractEntityDefinition , the AbstractActivatableEntityDefinition and the AbstractFilterableEntityDefinition:

When the promotion is fired, the client may buy several variants of a product and then receive several more for free. For example - buy 2 T-shirts and get one for free. The defined here property is rewardCount (stores an Integer).
The ProductBundlePromotionEntityDefinition extends the ProductPromotionEntityDefinition:

When the promotion is fired, the client may purchase several products and get a bundle price for them. For example - purchase a T-shirt and a pair of shorts for 20 EUR.
The ProductFixedPricePromotionEntityDefinition extends the ProductPromotionEntityDefinition:

When the promotion is fired, the client may purchase specified products on a defined, lower price. For example - buy any pair of shorts for 7 EUR. The defined property here is price. It stores a set of prices for the promotion to apply when the promotion is fired.
The ProductMultibuyPromotionEntityDefinition extends the ProductPromotionEntityDefinition:

When the promotion is fired, the client may purchase several products from a given range of products for a fixed price. For example - purchase any 5 T-shirts for 15 EUR.
The ProductOneToOnePerfectPartnerBundlePromotionEntityDefinition extends the ProductPromotionEntityDefinition:

When the promotion is fired, the client may buy a specified combination of 2 products on a reduced price. For example - buy a shirt and a pair of trousers for 25 EUR.
The ProductPercentageDiscountPromotionEntityDefinition extends the ProductPromotionEntityDefinition:

When the promotion is fired, the client may buy certain sets of products with a percentage discount. For example - all of the shorts are 10% OFF. Keep in mind that all other relevant promotions will be discarded. The defined property here is value. It stores the value of the percentage discount that will be applied when the promotion is fired.
The ProductPerfectPartnerBundlePromotionEntityDefinition extends the ProductPromotionEntityDefinition:

When the promotion is fired, the client may purchase a certain product and a number of other products to create a bundle for a special price. For example - buy a pair of white trainers and choose 3 t-shirts for 30 EUR only.
The ProductPerfectPartnerPromotionEntityDefinition extends the ProductPromotionEntityDefinition:

When the promotion is fired, the client may purchase a certain product from a set of products, and another product from another set to get a fixed price for the second product. For example - buy a pair of shorts and get any T-short for 5 EUR.
the ProductPromotionEntityDefinition extends the PromotionEntityDefinition:

This is the base promotion for all product promotions. Via the respective getter-setter pairs, the following information can be retrieved/stored in the database:
Property | Description |
---|---|
categories |
stores a set of categories for the promotion |
products |
stores a set of products the promotion is applicable for |
activeCountThreshold |
stores the activated count threshold for the promotion |
potentialCountThreshold |
stores the potential count threshold for the promotion |
The ProductSteppedMultibuyPromotionEntityDefinition extends the ProductPromotionEntityDefinition:

When the promotion is fired, the client may purchase a number of products from a defined set with multiple steps. For example - buy any 3 T-shirts for 10 EUR, any 5 T-shirts for 20 EUR or any 10 T-shirts for 30 EUR.
Spring Data JPA Repositories
The PromotionGroupRepository extends the BaseEntityRepository and is the corresponding Spring Data JPA repository for the PromotionGroupEntityDefinition
:

The PromotionPriceRowRepository extends the BaseEntityRepository and is the corresponding Spring Data JPA repository for the PromotionablePriceEntityDefinition
:

The PromotionRepository extends the BaseEntityRepository and is the corresponding Spring Data JPA repository for the PromotionEntityDefinition
:

The PromotionResultRepository extends the BaseEntityRepository and is the corresponding Spring Data JPA repository for the PromotionResultEntityDefinition
:

Order-related Repositories
The OrderThresholdChangeDeliveryModePromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the OrderThresholdChangeDeliveryModePromotionEntityDefinition
:

The OrderThresholdFixedDiscountPromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the OrderThresholdFixedDiscountPromotionEntityDefinition
:

The OrderThresholdFreeGiftPromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the OrderThresholdFreeGiftPromotionEntityDefinition
:

The OrderThresholdFreeVoucherPromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the OrderThresholdFreeVoucherPromotionEntityDefinition
.

The OrderThresholdPerfectPartnerPromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the OrderThresholdPerfectPartnerPromotionEntityDefinition
:

Product-related Repositories
The ProductBOGOFPromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the ProductBOGOFPromotionEntityDefinition
:

The ProductBundlePromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the ProductBundlePromotionEntityDefinition
:

The ProductFixedPricePromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the ProductFixedPricePromotionEntityDefinition
:

The ProductMultibuyPromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the ProductMultibuyPromotionEntityDefinition
:

The ProductOneToOnePerfectPartnerBundlePromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the ProductOneToOnePerfectPartnerPromotionEntityDefinition
:

The ProductPercentageDiscountPromotionRepository extends the ActivatableRepository and the BaseEntityRepository. This is the corresponding Spring Data JPA repository for the ProductPercentageDiscountPromotionEntityDefinition
.

The ProductPerfectPartnerBundlePromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the ProductPerfectPartnerBundlePromotionEntityDefinition
:

The ProductPerfectPartnerPromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the ProductPerfectPartnerPromotionEntityDefinition
:

The ProductSteppedMultibuyPromotionRepository extends the ActivatableRepository and the BaseEntityRepository . This is the corresponding Spring Data JPA repository for the ProductSteppedMultibuyPromotionEntityDefinition
:

Business Services
Among the helper functionalities, defined within the PromotionResultService, are:
Description | Method |
---|---|
to check if a promotion is applied |
isApplied() |
to check if a promotion is applied to an order |
isAppliedToOrder() |
to check if a promotion is fired |
getFired() |
to check if a promotion could be fired |
getCouldFire() |
to get a promotion’s description |
getDescription() |
to apply a promotion |
apply() |
to undo a promotion |
undo() |
to obtain the consumed count of a promotion |
getConsumedCount() |
to obtain the total discount of a promotion |
getTotalDiscount() |
Among the helper functionalities, defined within the PromotionsService, are:
Description | Method |
---|---|
to get the list of promotions of a given type for the given order |
getPromotionResults() |
to fire the promotions found for the website and to recalculate the order |
firePromotions() |
Facade
MapperFactoryConfigurers
The PromotionCartMapperFactoryConfigurer implements the MapperFactoryConfigurer , converting the CartEntityDefinition
to CartPromotionDtoDefinition
:

The conversion is customized.
The PromotionDeliveryModeMapperFactoryConfigurer implements the MapperFactoryConfigurer, converting the PromotionDeliveryModeEntityDefinition
to DeliveryModeDtoDefinition
:

The conversion is customized.
The PromotionMapperFactoryConfigurer implements the MapperFactoryConfigurer , converting the PromotionEntityDefinition
to PromotionDto
:

The conversion is customized.
The PromotionOrderEntryMapperFactoryConfigurer implements the MapperFactoryConfigurer, converting the PromotionableAbstractOrderEntryEntityDefinition
to OrderEntryPromotionDtoDefinition
:

The conversion is customized.
The PromotionOrderMapperFactoryConfigurer implements the MapperFactoryConfigurer, converting the OrderEntityDefinition
to OrderPromotionDtoDefinition
:

The conversion is customized.
The PromotionResultMapperFactoryConfigurer implements the MapperFactoryConfigurer, converting the PromotionResultEntityDefinition
to PromotionResultDto
:

The conversion is customized.
Dto definitions
The CartPromotionDtoDefinition extends the OrderPromotionDtoDefinition:

This is the corresponding Dto object for the CartEntityDefinition
.
The OrderEntryPromotionDtoDefinition is the corresponding Dto object for the PromotionableAbstractOrderEntryEntityDefinition
.
The OrderPromotionDtoDefinition is the corresponding Dto object for the OrderEntityDefinition
.
The PromotionCartDtoDefinition extends the CartDtoDefinition and the CartPromotionDtoDefinition. Тhe inheritance goes further, to the AbstractCartDtoDefinition, the OrderDiscountsDtoDefinition, the OrderEntriesDtoDefinition, the OrderDeliveryAddressDtoDefinition, the OrderDeliveryMethodDtoDefinition, the OrderPaymentInfoDtoDefinition, the OrderDeliveryOrderEntryGroupsDtoDefinition and the OrderPickupOrderEntryGroupsDtoDefinition:

The PromotionDetailsProductDtoDefinition extends the DetailsProductDtoDefinition and the ProductPromotionDtoDefinition. The inheritance goes further to the UrlProductDtoDefinition, the DetailsDtoDefinition, the AbstractProductDtoDefinition and the ProductUrlDtoDefinition:

The PromotionDto is the corresponding Dto object for the PromotionEntityDefinition
.
The PromotionOrderDtoDefinition extends the OrderDtoDefinition and the OrderPromotionDtoDefinition. The inheritance goes further to the AbstractOrderDtoDefinition, the OrderDiscountsDtoDefinition, the OrderEntriesDtoDefinition, the OrderDeliveryAddressDtoDefinition, the OrderDeliveryMethodDtoDefinition, the OrderPaymentInfoDtoDefinition, the OrderDeliveryStatusDtoDefinition, the OrderStatusDtoDefinition, the OrderPickupOrderEntryGroupsDtoDefinition and the OrderDeliveryOrderEntryGroupsDtoDefinition:

The PromotionOrderEntryDtoDefinition extends the OrderEntryDtoDefinition and the OrderEntryPromotionDtoDefinition:

The PromotionOrderEntryProductDtoDefinition extends the OrderEntryProductDtoDefinition and the ProductPromotionDtoDefinition. The inheritance goes further to the AbstractOrderEntryProductDtoDefinition, the ProductDescriptionDtoDefinition, the ProductDiscountDtoDefinition, the ProductGalleryImagesDtoDefinition, the ProductBaseOptionsDtoDefinition and the ProductVariantOptionsDtoDefinition:

The PromotionResultDto is the corresponding Dto object for the PromotionResultEntityDefinition