Discount Rules / Rewards
Define when a Discount should apply and what should be the Reward in Umbraco Commerce.
Discounts in Umbraco Commerce are defined using a series of rules and reward builders that let you configure the following:
When a Discount should apply.
What the Reward should be for that Discount.
These builders come with a handful of the most common Rules and Rewards that should suit the majority of web stores' needs. When need to create your own Rules or Rewards then these are extendable via a Provider model allowing you to incorporate your own custom logic.
Discount Rules
There are two types of Discount Rules in Umbraco Commerce:
Order Discount Rules: Determine whether a discount should apply to an Order. Returns a Fulfilled/Unfulfilled status depending on whether the Rule logic has been met.
Order Line Discount Rules: Determine whether a discount should apply to an Order Line within an Order. Returns a Fulfilled/Unfulfilled status depending on whether the Rule logic has been met. Where the status is Fulfilled, a list of all Order Lines that are fulfilled by this Rule is also returned.
Example: Custom Order Discount Rule Provider
An example of an Order Discount Rule Provider would look something like this:
All Order Discount Rule Providers inherit from a base class OrderDiscountRuleProviderBase<TSettings>
. TSettings
is the type of a Plain Old Class Object (POCO) model class representing the Discount Rule Providers settings.
See the Settings Objects section below for more information on Settings objects.
The class must be decorated with DiscountRuleProviderAttribute
which defines the Discount Rule Providers alias
and name
, and can also specify a description
or icon
to be displayed in the backoffice. The DiscountRuleProviderAttribute
is also responsible for defining a labelView
for the Provider.
See the Label views section below for more information on Label Views.
Rule Providers have a ValidateRule
method that accepts a DiscountRuleContext
as well as an instance of the Providers TSettings
settings model. Inside this you can perform your custom logic, returning a DiscountRuleResult
to notify Umbraco Commerce of the Rule outcome.
If the passed-in context (which contains a reference to the Order) meets the Rule's criteria, then a fulfilled DiscountRuleResult
can be returned by calling return Fulfilled();
. Alternatively, if the Order didn't meet the Rules criteria an unfulfilled DiscountRuleResult
can be returned by calling return Unfulfilled();
.
Example: Custom Order Line Discount Rule Provider
An example of an Order Line Discount Rule Provider would look something like this:
All Order Line Discount Rule Providers inherit from a base class OrderLineDiscountRuleProviderBase<TSettings>
and follows much the same requirements as the Order Discount Rule Provider defined above. Where they differ is in the ValidateRule
method implementation and when a fulfilled DiscountRuleResult
is returned. In this case, an Order Line Discount Rule returns a collection of Order Lines processed by the Rule that have met the rules criteria. Whether the rules are met, is checked by calling return Fulfilled(fulfilledOrderLines);
.
Discount Rewards
Example: Custom Discount Reward Provider
An example of a Discount Reward Provider would look something like this:
All Discount Reward Providers inherit from a base class DiscountRewardProviderBase<TSettings>
. TSettings
is the Type of a POCO model class representing the Discount Reward Providers settings.
See the Settings Objects documentation for more information on Settings objects.
The class must be decorated with DiscountRewardProviderAttribute
which defines the Discount Reward Providers alias
and name
. It can also specify a description
or icon
to be displayed in the Umbraco Commerce backoffice. The DiscountRewardProviderAttribute
is responsible for defining a labelView
for the Provider.
See the Label views section below for more information on Label Views.
Reward Providers have a CalculateReward
method that accepts a DiscountRewardContext
as well as an instance of the Providers TSettings
settings model. Inside this, you can perform your custom calculation logic, returning a DiscountRewardCalculation
instance that defines any Reward values to apply to the Order.
Common Features
Settings Objects
See the Settings Objects documentation for more information on Settings objects.
Label Views
Both the DiscountRuleProviderAttribute
and the DiscountRewardProviderAttribute
allow you to define a labelView
for the Provider. It should be the path to an Angular JS view file that will be used to render a label in the Rule/Reward Builder UI. Where no labelView
is supplied, one will be looked for by convention at the following location:
~/app_plugins/umbracocommerce/views/discount/{Type}/labelViews/{ProviderAlias}.html
Type
is either rules
or rewards
, depending on the Type of Provider it refers to. ProviderAlias
is the alias of the Provider.
The Rule/Reward Label View should provide a user-friendly summary of its settings to display in the relevant Builder UI.
The Label View file will be passed a model
property which will be a JavaScript representation of the given Providers settings object.
Last updated