- v1.0.0-latest-prod
The Offer Service supports many advanced offer concepts and use cases. This section describes the key features supported by the offer service.
Offers can be created to discount an order, specific items, shipping (fulfillment) charges, item shipping charges, or generate a voucher for a future order.
For more details on setting up offers of different types, see Offer Types.
Discount methods are one of the following: amount off, fixed price, or percent off. Discount methods are used in combination with the discount type to determine where the discount is applied and how much should be discounted. Additional features can be added onto that combination to further inform or restrict the discount. For more details on setting up offers of different types, see Offer Types.
Item offers can use tiers to apply different discounts based on minimum/maximum quantity or price values. For example, buy 1 to 2 for $10 each or 3 or more for $8 each; or, buy $10 to get 10% off or buy $50 to get 20% off. Tiered offers apply to order item level offers and can use amount off, fixed price, or percent off.
Offers can be automatically applied meaning all customers whose order qualifies will get the discount.
Alternatively, offers can be setup to use a single-use or multi-use offer code. Campaigns are used in conjunction with offers to generate large numbers of single-use codes.
Offers have an active date ranges that are used to restrict when the offer can be used.
Additional offer criteria can be configured to restrict offer usages based on the current time using time-based rules.
Default combinability by discount type:
Order discounts can have up to one ORDER discount, but may combine with offers of other discounts types.
Order Items can have up to one DISCOUNT per ITEM quantity, and may combine with offers of other discount types.
Fulfillment discounts can have up to one FULFILLMENT_GROUP discount, but may combine with offers of other discounts types.
Fulfillment item discounts can have up to one FULFILLMENT_GROUP_ITEM discount, but may combine with offers of other discounts types.
Vouchers can be applied at most once per order, but may combine with offers of other discounts types.
Offers can be setup to allow multiple, stacked ORDER and/or ITEM offers. Offers can also be setup to be the ONLY offer in the order regardless of type.
The default combinability settings are generally sufficient. See the Stacking and Combinability page for a more details.
Using single-use or limited-use codes is a good way to limit offer usage. See offer code usage limits for more details.
Other methods that can be enabled with offer setup include:
Max uses across all customers (e.g. 1st 100 users)
Max uses within a cart (e.g. allow up to 3 discounts in a single order)
Max uses for a given customer or account (e.g. only allow 1 discount per customer)
Max uses for a given customer within a set timeframe (e.g. only allow 3 discounts per customer within 5 days)
Max total savings (e.g. offer can only discount $5000 total across all orders and customers)
Max savings per order (e.g. up to $50 for a single order)
Offers can be restricted based on the dollar amounts for the order. There use case supported with spend qualifications are:
Minimum cart total
Minimum total of items within a fulfillment group
Minimum total of discount targeted items
Minimum total of qualifying items
Offers can have associated marketing messages. Marketing messages allow for messages to be to be available for display on PDP, cart, search results, or other pages. These messages can be configured to show based on whether or not the offer is applied to the cart. Marketing messages can also be configured to display on the target items, qualifier items, or both.
See the Marketing Message APIs for more information.
Offers can be managed globally (at the tenant level) or at the application level. Apply offers will consider for both tenant and application offers.
|
Note
|
Offers may have different currencies across applications, so offers built at the tenant level should specify a specific currency or the offer will attempt to the currency. The currency is resolved first based on the currency passed on the context request, but if the currency was not specified on the context it will resolve based on the order currency. The offer fields that would be affected by currency are any subtotal-based restrictions, tiered offers, and the discount method if it is not percent off. |
The Offer criteria rules are powered by the Broadleaf RulesEngine.
For Item Offers, rules can be added to specify which items are eligible to receive the discount.
Target Item rules are a set of given rules that must match an item within the cart for the offer to apply. The offer will apply only to the items that match the given criteria of the target item rules. If there are multiple items that match the criteria, but a limited number of times the offer can apply, then only a limited number of items will receive the discount, starting either at the cheapest or most costly item depending on the target grouping strategy.
For Item Offers, rules can be added to specify if the order is qualified to receive the discount.
Qualifier Item rules are a set of given rules that must match an item or items within the cart for the offer to apply. An example of the qualifier is the "buy" item in a BOGO offer. The "buy" item qualifies the customer to receive a discount on their "get" item.
Qualifier items do not receive a discount from other item offers, unless they are configured to be able to receive a discount. For example, in the use case of a BOGO you would use a qualifier rule to denote the item that is the “buy” item, and the “get” item would be configured as the target. However, you could also set up another offer that applies to all items in the cart. If configured that qualifiers can be targets, then the qualifier item would also receive a discount. Otherwise, the qualifier would not be eligible to receive the discount.
Offers can be restricted by attributes on the order. For example, the offer could specify that it can only apply to orders of a specific locale or currency.
Offers do not require a priority and it is not usually required to set the priority. By default, the offer engine will attempt to choose the combination of offers that provides the most favorable deal to the customer. Priorities allow for explicit control of the order in which offers will be considered.
The Broadleaf admin provides the ability to make offer changes through the preview and approval workflows.
For more details on the admin change workflow, see Data Workflow.
This service includes the following out-of-box import implementations.
(offer codes supported since 2.0.0-GA)
Offer Codes and Campaign Codes can both be imported, and the components to support them are shared.
The import type is either OFFER_CODES or CAMPAIGN_CODES, and the corresponding specification in ImportServices is OfferCodeSpecification for offer code imports and CampaignCodeSpecification for campaign code imports.
Key Components:
|
Note
|
Prior to
They have been removed and replaced with the components described below. |
OfferCodeImportBatchHandler is responsible for processing imports of OfferCode entities either for Offer(s) or for Campaign(s)
OfferCodeConverter is responsible for converting input offer code rows into OfferCode instances
OfferCodeDefaultsInitializer assists in initializing values on OfferCode instances if not already set
Audit details are collected and stored to enforce offer and offer code max usage.
Which audit checks should run for each flow is controlled by the audit verification properties. By default, the audit checks are disabled for the apply offers flow and the marketing message retrieval. Audit checks are enabled by default on the code usability and offer & offer code validation APIs.
Every time an offer is used in the checkout workflow, its usage is recorded as part of the post-checkout events.
The listener configured for these events, RecordOfferUsageEventListener.java, processes the messages and build audit details as needed.
Each offer usage is represented by an OfferAuditDetail.
By default, these are only recorded if the offer code has max usages, the offer has per customer max usages, or if the property alwaysRecordCustomerDetailAudit is set to true.
Each offer is represented by an OfferAuditSummary. This is updated after each offer usage to increment the number of times the offer has been used and the total discount amount that the offer has provided.
Each offer code is represented by a SharedCodeAuditSummary. This is updated after each offer code usage to increment the number of times the offer code has been used and the total discount amount that the offer code has provided.
This approach to code usage has a small race condition where two checkouts can simultaneously use the same code if they hit submit in the same few seconds. This architectural decision is by design as other approaches (such as reserving or locking the code) have significant downsides with regard to use and ability to scale the function. For implementations that see this as a concern, it is preferable in most cases to provide post checkout audits prior to fulfillment rather than to handling during the submit checkout flow.
Offer Codes include both offer codes that can be added directly onto an offer, and campaign codes
created from a campaign. These are both backed by the same domain and classes as of 2.0.0-GA.
When offer code(s) do not apply, a list of See offer code responses is returned.
Offer codes can be setup to limit usage with max usage limits. Max usage restrictions can be enabled for the following:
Max uses across all customers (e.g. 1st 100 users)
Max uses for a given customer or account (e.g. only allow 1 discount per customer).
Specifically this restricts the number of orders a user can apply the offer or code to.
Also note that setting this also means that no anonymous customers can use the offer or code.
In addition to being single or limited use, codes for campaigns can be restricted to certain users.
This can be done with individual emails on each code or by using an Email Regular Expression such as *@mycompany.com.
Offer codes have an active date ranges that are used to restrict when the offer code can be used.
Codes can be imported and exported into an offer or campaign.
For campaigns, this is designed to support offline merging of codes and qualifying emails. For example, if you have generated a set of codes, you can then export these codes to be used in an email campaign. Further, you could optionally pair an email address with each code to further restrict the use of the code to a specific customer.
For offers, this allows the admin to register offer codes to an offer without being associated with a campaign.
Further details can be found at Importing offer and campaign codes.
Campaigns support grouping offer codes and generation of single-use offer codes. These can be helpful when building out an email campaign to provide promotion codes to customers.
Campaigns can specify a prefix that all generated codes will have appended to the start of the code string.
Campaigns have an active date ranges that are used to restrict when the campaign can be used.
A CodeGenerator is the component that controls the code generation process. There are several
key properties and classes to be aware of for code generation.
The code generation generates codes according to a target format. The format has placeholders that drive the set of characters that can be used.
Consider the code format: TEST1-@@-##-*
This format has a hardcode prefix of "TEST1-" and 3 sets of placeholder values.
The "@" placeholder will use allowed alphabetic characters when generating the code.
The "#" placeholder will use allowed numeric symbols when generating the code.
The "*" placeholder will use allowed alphanumeric symbols when generating the code.
The DefaultCodeGeneratorService uses the CodeFormatAvailableCharHelper to determine the
allowed symbols for code generation. By default, the allowed numbers exclude 0, 1, and 5. The
allowed characters exclude I, L, O, and S. These characters are excluded from generated offer
codes to avoid commonly misread letters and numbers.
These components can be customized for more precise code generation strategies.
If no format is provided, the code generation service will generate a code based on the code generators specified length. If no length or format is provided to the code generator, it will select an appropriate length based on a guessability ratio of 1 and 100.
During code generation, campaigns can specify restrictions on which letters or numbers are allowed in the code string. When the codes are generated, the code string will be limited to only those specified letters or numbers. Otherwise, by default, the allowed numbers include "2346789" and the allowed letters include "ABCDEFGHJKMNPQRTUVWXYZ".