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

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.


  1. The customer enters the voucher code.
  2. 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.
  3. 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.
  4. At the end of the checkout process, an order is created from the cart.
  5. 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).


  •  The voucher uses extensively the jalo layer. 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.

Based on Hybris Version 5.3

Add comment

Security code