Promotions are a means of offering discounts on an order based on various criteria. A Promotion consists of conditions and actions.
All Promotions can have the following constraints applied to them:
applyCouponCode mutation in the Shop API.A Promotion may be additionally constrained by one or more conditions. When evaluating whether a Promotion should be applied, each of the defined conditions is checked in turn. If all the conditions evaluate to true, then any defined actions are applied to the order.
Vendure comes with some built-in conditions, and you can also create your own.
A promotion action defines exactly how the order discount should be calculated. At least one action must be specified for a valid Promotion.
Vendure comes with some built-in actions, and you can also create your own.
For details on creating custom conditions and actions, see the Developer Guide.
To create a custom condition, you need to define a new PromotionCondition object.
Here is an annotated example of one of the built-in PromotionConditions.
Custom promotion conditions are then passed into the VendureConfig PromotionOptions to make them available when setting up Promotions:
There are three kinds of PromotionAction:
PromotionItemAction applies a discount on the OrderLine level, i.e. it would be used for a promotion like "50% off USB cables".PromotionOrderAction applies a discount on the Order level, i.e. it would be used for a promotion like "5% off the order total".PromotionShippingAction applies a discount on the shipping, i.e. it would be used for a promotion like "free shipping".Here's an example of a simple PromotionOrderAction.
Custom PromotionActions are then passed into the VendureConfig PromotionOptions to make them available when setting up Promotions:
PromotionActions support a side effect API with onActivate/onDeactivate hooks, which allow you to define additional actions to be performed when a Promotion becomes active or inactive.
A primary use-case of this API is to add a free gift to the Order. Here's an example of a plugin which implements a "free gift" action:
It is possible to establish dependency relationships between a PromotionAction and one or more PromotionConditions.
For example, if we want to set up a "buy 1, get 1 free" offer, we need to:
In this scenario, we would have to repeat the logic for checking the Order contents in both the PromotionCondition and the PromotionAction. Instead, we can say that the PromotionAction depends on the PromotionCondition:
In the above code, we are stating that this PromotionAction depends on the buyXGetYFreeCondition PromotionCondition. Attempting to create a Promotion using the buy1Get1FreeAction without also using the buyXGetYFreeCondition will result in an error.
In turn, the buyXGetYFreeCondition can return a state object with the type { [key: string]: any; } instead of just a true boolean value. This state object is then passed to the PromotionConditions which depend on it, as part of the last argument (state).
If your PromotionCondition or PromotionAction needs access to the database or other providers, they can be injected by defining an init() function in your PromotionAction or PromotionCondition. See the configurable operation guide for details.