====== Promotion module: Key concepts and features =====

This extension enables the management of customer sales promotions.

<WRAP center round important 100%>
This extension is deprecated since SAP Hybris 6.1. You must use the the Promotion Engine for new projects. [[https://help.sap.com/viewer/9d346683b0084da2938be8a285c0c27a/1905/en-US/c844a77cd9674d678ffb5e4534ff136a.html|Promotions (Legacy) vs. Promotion Engine]]
</WRAP>

===== Key Concepts ======

  * **Promotion**: Discount which is automatically applied to a cart or order, when some conditions are met.
  * **Product Level Promotions**\\ 
    * **Bundle**: Fixed price when buying A, B or C.
    * **Buy X get Y free**
    * **Fixed price** for a set of products
    * **Multi-buy:** Fixed price of many products from a set
    * **One to one perfect partner bundle:** Two defined products for a fixed price.
    * **Percentage discount**
    * **Perfect partner:** Products for two categories for a fixed price.
    * **Perfect partner bundle****:** One product and many additional products from a set for fixed price.
    * **Stepped multi-buy:** Discount by buying a higher quantity of the same product.
  * **Order Level Promotions**\\ 
    * **Free gift** with an order over $ X
    * **Free voucher** with an order $ X
    * **Fixed Discount** with an order over $ X 
    * **Free shipping** or faster shipping with an order over $ X
    * **Order threshold perfect partner:** If you spend more than $ 100, you get any coffee capsules for $ 3 
  * **Restrictions**
    * Start and end date.
    * User groups: some users can or cannot use this promotion
    * Product: Some products can't be applied to the current promotion. **This product could be used with another promotion.**
    * Order: The promotion can only be applied to some given orders.
    * Store: The promotion can only be applied in some stores.

===== Key Features ======

  * Promotions are **inactive by default.** They must be activated, when they are completely configured.
  * Each promotion points to **URL** which describes the promotion
  * **Evaluation**
    * Active Promotions evaluation: Which promotions are included in the cart?
      * They consume the cart entries.
      * It generates entry or order discounts
      * The promotion with the highest priority is evaluated first
      * A fired message can be shown. For example: "You have received 3 boxes for $33, saving $7".
    * Partial Promotion evaluation: Which promotions could be fired?
      * They don't consume cart entries to allow the extension to calculate other possible promotions
      * It doesn't generate any discount
      * It returns the probability of firing the promotion.
      * A "could be fired" message can be shown. For example: "Add 1 box to get 3 boxes for $33, saving $7".
    * Hybris will automatically create order or entry discounts when the promotion is applied. The type of discount depends on the type of promotion.
  * A **cache** could be activated to improve the performance of the calculation of the promotions.\\ 
    * The results of the evaluation using the cache are persisted after the promotion is applied to an order. Before that point in time, they are stored in the session. When a persisted cart is restored, the promotions must be recalculated.
    * A cluster-aware implementation could be developed.
  * Promotions can be **grouped**

===== Workflow ======

Please use this advise carefully, as I wasn't able to check if this workflow actually works.

  - The customer adds or removes products to the cart
  - The cart is recalculated
  - The method PromotionService.updatePromotions(...) is called.
  - The result are returned. it includes the fired and the potential promotions, the entries used in the fired or potential promotions and a flag indicated of there were changes since the last evaluation.
  - If the cart is updated, it must be recalculated and reapplied
  - At the end of the checkout process the order is created using the cart.
  - The promotions are applied to the order by calling the PromotionService.transferPromotionsToOrder.
  - Now the persisted promotions or their results are returned by calling PromotionService.getOrderPromotions(...) and getPromotionResults(...)

The promotions and their results can be removed from the cart by calling PromotionService.cleanupCart(...)


===== Pitfalls ======

  * **Neither a cart nor an order is aware of promotions.**  [[https://help.sap.com/viewer/9d346683b0084da2938be8a285c0c27a/1905/en-US/8c35447a86691014b9b78b4c2e8af362.html|After any change to the cart or order, you have to recalculate it and then call the method PromotionsService.updatePromotions(...)]]
  * **This extension uses the jalo layer**. The PromotionService delegates the calls to the promotion manager.

--Based on Hybris Version 6.1