====== Vouchers - Key Concepts and Features =====

The voucher extension allows the business to create and manage public promotions, bonus or compensation for the customers, discounts for the employees or gifts.

<WRAP center round important 100%>
This extension is deprecated since SAP Hybris 6.3. You must use the coupons of 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 ======

  * **Voucher**: Special discount which must be actively redeemed by the customer
  * **Promotional Voucher:** They have one unique code which may be redeemed by many customers
  * **Serial Voucher:** They a list of valid codes. Each of them can be redeemed once.
  * **Redeeming a voucher:** Assigning it to a cart.
  * **Releasing a voucher:** Removing it from a cart.
  * **Voucher Restrictions:** They constraint the use of the voucher. A voucher can be redeemed only if the order fulfills all the restrictions.

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

  * Vouchers
    * They have a **fixed or percentual discount.** When the field currency is empty, they have percentual discount.
    * They may have **free shipping.**
    * They has a **Promotion Code** (3 letters) to track the campaign and a long **voucher code (15 letters)** for the customer.
    * The number of voucher redeemed in total and per customer can be limited.
  * **Restrictions**
    * By order count. Minimum number of orders. (RegularCustomerOrderQuantityRestriction)
    * By revenue (incl. or excl. VAT)  of past orders (RegularCustomerOrderTotalRestriction)
    * For new customer (without any previous order) (NewCustomerRestriction)
    * By net or gross total of the order (OrderRestriction)
    * For some products (ProductRestriction)
    * For some ordered quantity of products (minimum or maximum) (ProductQuantityRestriction)
    * For some categories (ProductCategoryRestriction)
    * For some user group (UserRestriction)
    * During some period of time (DateRestriction)
    * Most restrictions may be inverted (field positive).
    * The violation message can be configured
  * Vouchers and restrictions can be easily created with HMC.

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

  - The customer enters the voucher code.
  - The eShop calls VoucherService.redeemVoucher(voucherCode, currentCart)
    * The cart is recalculated (using jalo)
    * Each restriction is checked
    * If the cart fulfills all the restrictions, the applicable entries are calculated. **Based on the total price of the applicable entries -which fulfill all the restrictions- the value of the discount is calculated.**
    * If one restriction isn't fulfilled, the voucher isn't redeemed.
    * This method doesn't reserved the voucher code. Another customer can still add the same code to another cart.
  - **If the customer adds or removes products to the cart and any voucher restriction isn't fulfilled, the voucher stays assigned to the cart but the discount would be zero.**
  - At the end of the checkout process, an order is created from the cart.
  - The voucher code must be applied to the order calling VoucherService.redeemVoucher(voucherCode, order). This method returns a VoucherInvalidationModel which is an association between the voucher, the customer and the order. This limits the number of redemptions per customer.

The voucher may be released calling voucherService.release(aVoucherCode, aCart) or voucherService.release(aVoucherCode, anOrder).

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

  *  **The voucher uses extensively the jalo layer.** Please read the long explanation below. The voucher service delegates the calls to the voucherManager
    * After the redemption or the release the cart is recalculated using the jalo layer (price factory). If you have any custom code in the **calculationService** (like the calculation of special prices or delivery costs), you would have to recalculate the cart or order with the calculation service after calling the voucher service.
    * Your custom voucher restrictions must implement the jalo methods Restriction.isFulfilledInternal(AbstractOrder paramAbstractOrder) and Restriction.isFulfilledInternal(Product paramProduct). This code will stop working if the extension is migrated to the model layer.
    * To get the applicable value of the voucher you have to use the jalo layer.
  * **The voucher code is saved separately from the voucher model in the cart.** You would have to call the voucher service to get each one of them. The discount saved in the cart doesn't store the voucher code.
  * The serial vouchers only work in the database which generated them. **You cannot import a list of serial vouchers codes into another system**. If you want to use serial vouchers in your integration or unit test you have to generate a voucher code on the fly at the beginning of the test.

==== Use of the Jalo Layer in the voucher extension ====
The Voucher extension hasn't migrated yet to the model layer and the creation, redeem and removal of vouchers depends heavily on Jalo attributes which aren't accessible in the model layer. This means that any custom code you implement for the vouchers will have an akward mix of jalo and model layers calls. There are also some pitfalls you must be aware of.

=== Calculation of the cart ======

  * After a voucher is redeemed or removed, the voucher extension recalculates the cart using the jalo layer. If you have written your own calculation service, you would have to recalculate the cart again because the voucher extension doesn't call your custom logic but the old price factory class.
  * If you have cart with a valid voucher and a product is removed or added or its quantity is changed, the restrictions of the voucher aren't checked. If the restrictions aren't fullfilled, the discount of the voucher isn't applied and you don't get any exception. If you want to remove the voucher from the cart, you would have to recheck if the voucher is applicable to cart and remove the voucher if is not.

=== Place Order ======

When you clone a cart to create the order, the list of applied voucher codes won't be copied. The field AbstractOrder.appliedVoucherCodes is private. Due to this no accessors are created for the model. Another issue is that vouchers aren't consumed when you copy them to the order.

To avoid this issue you have to clone the order from the cart, remove the vouchers and reapply them:
<code java>
public void transferVouchers(final CartModel cart, final OrderModel order)
  {
    final Collection appliedVouchers = getAppliedVoucherCodes(cart);
    //We remove any voucher discount which may be copied.
    removeAllVouchers(order);
    for (final String voucherCode : appliedVouchers)
    {
      redeemVoucher(voucherCode, order);
    }
  }

/**
   * Removes all the voucher information from the abstract order. It is used after an order was created from a cart.
   *
   * @param pAbstractOrderModel
   */
  private void removeAllVouchers(final AbstractOrderModel pAbstractOrderModel) {
    for (DiscountModel aDiscount : pAbstractOrderModel.getDiscounts()) {
      if (aDiscount instanceof VoucherModel) {
        try
        {
          removeDiscount(null, pAbstractOrderModel, (VoucherModel)aDiscount);
        }
        catch (AcmeVoucherNotFoundException e)
        {
          if (LOG.isDebugEnabled())
          {
            LOG.debug("Unable to remove the voucher " + aDiscount + " from the list of discount. Ignoring the error.");
          }

        }
      }
    }
    removeAllAppliedVoucherCodes(pAbstractOrderModel);
  }

private void removeDiscount(final String pVoucherCode, final AbstractOrderModel pCartModel, final VoucherModel pVoucherModel)
      throws AcmeVoucherNotFoundException
  {
    final List newDiscounts = new ArrayList(pCartModel.getDiscounts());
    if (newDiscounts.remove(pVoucherModel))
    {
      pCartModel.setDiscounts(newDiscounts);
    }
    else
    {
      throw new AcmeVoucherNotFoundException("Unable to find the voucher "
          + (pVoucherCode == null ? pVoucherModel : "with the code " + pVoucherCode)
          + " in the cart.");
    }
    // We send the changes to the jalo class.
    this.modelService.save(pCartModel);
  }

private void removeAllAppliedVoucherCodes(final AbstractOrderModel pAbstractOrderModel)
  {
    final AbstractOrder jaloOrder = this.modelService.getSource(pAbstractOrderModel);
    jaloOrder.setProperty(
          GeneratedVoucherConstants.Attributes.AbstractOrder.APPLIEDVOUCHERCODES, new ArrayList());
  }
</code>

I would prefer to avoid using Jalo, but I can't. This problem is a known issue: [[https://wiki.hybris.com/pages/viewpage.action?pageId=186258194|https://wiki.hybris.com/pages/viewpage.action?pageId=186258194]]

=== Serial Vouchers ======

The code of the voucher is generated using a cipher and random values stored in the database. Due to this, you cannot reuse the code in another database. If you try to export and import the serial vouchers using Impex, the codes won't work because you cannot export the fields key, alphabet and the secret key. If you would like to use serial vouchers during your integration tests, you would have to create the code on the fly:

<code java>
String voucherCode = this.getCurrentCase().getVoucherCode();
if (voucherCode.length() == 3)
{
      voucherCode = this.getNewSerialVoucherCode(voucherCode);
}
</code>

--Based on SAP Hybris 5.3