OrderDiscount (PCR)
Use the OrderDiscount pipeline component to apply discounts to the shopping basket.
Intended use: Order Processing pipeline, Order Adjust Price stage.
In Component Properties dialog box, on the Order Discount tab, do the following.
Use this |
To do this |
|---|---|
Apply percent first |
When two or more discounts of equal priority but different types apply to a line item, selecting this causes percentage discounts to apply before currency discounts of the same priority. |
Apply currency first |
When two or more discounts of equal priority but different types apply to a line item, selecting this causes currency discounts to apply before percentage discounts of the same priority. |
Apply discount to basket items |
Select Least expensive first to apply discounts to the least expensive items in the basket first. Select Most expensive first to apply discounts to the most expensive items in the basket first. The default sort order is Most expensive first. The special sort orders are as follows:
The Awards sort order can be changed on the OrderDiscount property page UI. There are three sorts used by the OrderDiscount engine:
To modify the condition sort:
To modify the award sort:
For more information about how to override the query, see CSFLoadDiscounts. |
To troubleshoot, use pipeline logging with the discount tracing enabled. Set context.[_trace_discounts] = true in the pipeline context to enable discount tracing. It will write out an additional string into the dictionary tracing through the algorithm.
Click Apply to save your changes.
Values Read
The OrderDiscount component reads the following values from the indicated dictionaries.
Key |
Dictionary |
Description |
|---|---|---|
item._cy_iadjust_currentprice |
Order |
Required. The current price of the line items. Type: Currency (VT_CY) |
item.quantity |
Order |
Required. The total quantity of a line item. Type: Integer (VT_I4) |
item._cy_oadjust_adjustedprice |
Order |
Optional (default is 0.0). The total price of all the items, after all the discounts have been applied. Type: Currency (VT_CY) .gif "Note") Note:
Total price for the line item can be computed using the following:n_unadjusted*_cy_iadjust_currentprice+_cy_oadjust_adjustedprice.
|
item._n_unadjusted |
Order |
Optional (default is equal to the quantity). The quantity of line items that have not been adjusted (line items that are eligible to serve as discount conditions and receive discount awards). Type: Integer (VT_I4) |
item._product_* |
Order |
The product properties for each item. The column name is appended to form the key name. For more information, see the Remarks section. |
item.discounts_applied |
Order |
Optional. A dictionary that contains the IDs of the discounts that applied to this line item the last time that the OrderDiscount pipeline component was run. Keys are the IDs; values are the date/timestamps of the discounts. This is usually persisted with the Order dictionary and used by the OrderDiscount object to detect discount changes and warn the user when a discount has changed or been removed. Type: IDictionary (VT_DISPATCH) Note:
The format of the dictionary is a mapping from the discount ID (campaign item ID) to a last-modified timestamp (VT_DATE).
|
discounts_clicked |
Order |
Optional. The campaign item IDs of the click-required discounts that have been clicked. Type: SimpleList of Integers |
orderlevel_discounts_applied |
Order |
Optional. A dictionary with information about the discounts that were applied at the order level the previous time that the OrderDiscount component was run. It is usually persisted together with the Order dictionary and is used by the OrderDiscount object to detect discount changes and warn the user when a discount has changed or been removed. Type: IDictionary (VT_DISPATCH) Note:
The format of the dictionary is a mapping from discount ID (campaign item ID) to a last-modified timestamp (VT_DATE).
Note:
This dictionary should not be used for accounting systems.
|
Evaluator |
Context |
Required. The expression evaluator instance used to evaluate product, targeting context, and user expressions. Type: IExprEval (VT_DISPATCH) |
CacheManager |
Context |
Optional (unless the _discounts key was not set in the Order dictionary). A CacheManager object that is used for retrieving the cached set of discounts eligible for application. Type: ICacheManager (VT_DISPATCH) |
CacheName |
Context |
Optional (unless the _discounts key was not set in the Order dictionary). The name of the CacheManager cache that contains the cached set of discounts Type: String (VT_BSTR) |
MessageManager.pur_discount_removed |
Context |
The error message text (optional). |
MessageManager.pur_discount_changed |
Context |
The error message text (optional). |
_trace_discounts |
Context |
Optional (default is false). Determines whether the OrderDiscount component should generate tracing information. Type: Bool (VT_BOOL) Note:
When tracing is turned on, it has a minimal amount of performance overhead because the string must be generated with each aspect of the decisions made.
Note:
When enabled, the key _discounts_trace_info will be written to the Order dictionary.
|
Language |
Context |
Optional (unless one of the MessageManager object warnings is used) The MessageManager object language in which localized messages should be retrieved from the MessageManager object. Type: String (VT_BSTR) |
TargetingProfiles |
Context |
A dictionary that describes all the profiles to target. |
UserProfile |
Context |
Optional. A ProfileObject object that represents the current user that is used in evaluating discount eligibility requirement expressions. Type: IprofileObject or IDictionary (VT_DISPATCH) |
ContextProfile |
Context |
Optional. The TargetingContext profile to use for evaluating discount eligibility requirement expressions. This is usually a Dictionary object but may also be a Profile object. Type: IprofileObject or IDictionary (VT_DISPATCH) |
SiteName |
Context |
Optional. The site name, used only for reporting the SiteName as part of several limited error messages that may be reported to the Event log. Type: String |
Values Written
The OrderDiscount component writes the following values to the Order dictionary.
Key |
Description |
|---|---|
_discounts |
Not always written (if the _discounts list was set before the OrderDiscount object was run, it is not changed). A ContentList object that contains the discounts from the discounts cache that is based on the CacheName key in the pipeline context. For the structure of the ContentList object, see CSFLoadDiscounts. Type: ContentList (VT_DISPATCH) |
_winners |
Always written. A SimpleList object that contains the campaign item IDs of all discounts applied to the basket. Type: SimpleList (VT_DISPATCH) Note:
Used by the RecordEvent and IISAppendToLog components to record the fact that the campaign items were applied (SOLD events), usually in the Accept stage of the checkout pipeline.
|
_event |
Always written. Contains the name of the event to record. This should always be set to SOLD. Type: String (VT_BSTR) Note:
This value is used by the RecordEvent and IISAppendToLog components to record the fact that the campaign items were applied (SOLD events), usually in the Accept stage of the checkout pipeline.
|
item._cy_oadjust_adjustedprice |
Always written. The total price of all the items, after all the discounts have been applied. An item is adjusted if it received a discount or was used as a condition for a discount where either the reuse_condition_as_condition or reuse_condition_as_award flags were set to false. Type: Currency (VT_CY) Note:
Total price for the line item can be computed as the following:_n_unadjusted*_cy_iadjust_currentprice+_cy_oadjust_adjustedprice
|
item._n_unadjusted |
Always written. The number of items whose price remains unadjusted after discounts are applied. An item is adjusted if it received a discount or was used as a condition for a discount where either the reuse_condition_as_condition or reuse_condition_as_award flags was set to false. Type: Integer (VT_I4) |
item.discounts_applied |
Optional. A dictionary that contains the campaign item IDs of the discounts that applied to this item. The keys are the IDs. The values are the date-time stamps of the discounts. This is usually persisted together with the Order dictionary and used by the OrderDiscount object to detect discount changes and warn the user when a discount has changed or been removed. Type: IDictionary (VT_DISPATCH) Note:
The format of the dictionary is a mapping from discount ID (campaign item ID) to a last-modified timestamp (VT_DATE).
|
item._itemlevel_discounts_applied |
Optional (only written if one or more item level discounts apply to the line item). A SimpleList of dictionaries where each dictionary contains information about an item level discount that was applied to the line item. The order of the list is significant and represents the order in which the discounts were applied to this line item. The dictionary contains the following elements for each discount:
Type: Dictionary (VT_DISPATCH) |
item._cy_itemlevel_discounts_subtotal |
Not always written (only written if one or more item level discounts apply to the line item). Sum of all item level discounts apply to this line item. Type: Currency (VT_CY) |
orderlevel_discounts_applied |
Optional. This component writes discount_basket_display into each entry in this list. This is a dictionary with information about the discounts that applied at the order level the last time that the OrderDiscount component was run. This is usually persisted together with the Order dictionary and used by the OrderDiscount object to detect discount changes and warn the user when a discount has changed or been removed. Type: Dictionary (VT_DISPATCH) Note:
The format of the dictionary is a mapping from the discount ID (campaign item ID) to a last-modified timestamp (VT_DATE).
|
_orderlevel_discounts_detail |
This is a dictionary that maps special offer types to a list of order level discounts that applies for that special offer type. It is written here so that OrderDiscountApply can read the value and write it into the orderlevel_discounts_detail entries that it writes. Other components such as OrderDiscountApply or ShippingDiscountAdjust are responsible for actually applying the discounts. Each element is a dictionary. The exact format of the dictionary depends on whether the element represents a combination of percentage-off discounts of the same priority, or a single discount. The following are the dictionary entries if the element represents a single discount:
The following are the dictionary entries if the element represents a combined percentage-off discount:
The following are the dictionary entries that exist in both cases:
The order the elements appear in the list is significant, because it is the order that OrderDiscount has determined they should be applied. Type: Dictionary (VT_DISPATCH) Note:
A combined percentage discount will never reflect a value larger than 100 percent, even if the sum of the percentages of discounts in the discounts_combined list is larger than 100. The last contribution of the discount is considered as the only amount that will apply.
Note:
If the combination is already discounted 100 percent, no additional percentage discounts of the same priority will be considered as applied, even if they could apply. Therefore, they will not be written to the list.
|
_discounts_removed |
Optional. A SimpleList object that contains campaign item IDs of discounts that no longer apply to the basket since the last time that the pipeline was run. This key is written only if some discounts no longer apply. Type: SimpleList (VT_DISPATCH) Note:
If this key is set, OPPERRORLEV_WARN (2) is returned from the Execute method, and the MessageManager message pur_discount_changed is added to the _Basket_Errors list.
|
_discounts_changed |
Optional. A SimpleList object that contains campaign item IDs of discounts that have changed since the last time that the pipeline was run. This key is written only if some discounts have changed. Type: SimpleList (VT_DISPATCH) Note:
If this key is set, OPPERRORLEV_WARN (2) is returned from the Execute method and the MessageManager message pur_discount_changed is added to the _Basket_Errors list.
|
_Basket_Errors |
Optional (modified if _discounts_removed or discounts_changed is set). Error messages are written to this SimpleList object. Type: IsimpleList (VT_DISPATCH) Note:
Every Order dictionary has a _Basket_Errors list that is used to report nonfatal pipeline errors to the user.
|
_qualifying_discounts |
Optional (written only when one or more discounts meet their qualification, but the discount has nothing to which to apply). Discount item IDs of the discounts that meet their qualifications, but for which there is nothing to award are written to this SimpleList object. Type: IsimpleList (VT_DISPATCH) |
_discounts_trace_info |
Optional. Not always written (written only if context_trace_discounts was set to true). Contains information about discount decisions. Type: String (VT_BSTR) |
_<special_offer_type>_type |
Optional (legacy). Not always written. The type of an order level discount (for example, free shipping), if one applies. Another component in the pipeline (such as ShippingDiscountAdjust) applies the discount. The key name is formed from the string stored in the special_offer_type key in the ContentList object. Possible values are as follows:
More than one type of order level discount may apply to the same OrderForm. Type: Currency (VT_CY) .gif "Important note") Important Note:
This is a legacy key for backward compatibility with the Commerce Server 2000 OrderDiscount component. New development should use the _orderlevel_discounts_detail dictionary.
|
_cy_<special_offer_type>_value |
Optional (legacy). The value of an order level discount (for example, free shipping), if one applies. Another component in the pipeline (such as ShippingDiscountAdjust) applies the discount. This key is used only for custom discounts applied outside the pipeline. The key name is formed from the string stored in the u_special_offer_type key in the discount database. The value of the discount comes from the offer_value field in the ContentList object. Type: Currency (VT_CY) Important Note:
This is a legacy key for backward compatibility with the Commerce Server 2000 OrderDiscount component. New development should use the _orderlevel_discounts_detail dictionary.
|
_cy_<special_offer_type>_description |
Optional (legacy). The description of an order level discount if one applies. This key may be used to display when the discount applies somewhere on the page. The value comes from the description field in the ContentList object. Type: String (VT_BSTR) Important Note:
This is a legacy key for backward compatibility with the Commerce Server 2000 OrderDiscount component. New development should use the _orderlevel_discounts_detail dictionary or the item_orderlevel_discounts_applied dictionary to obtain the item IDs. It can then look up the discount descriptions from the _discounts ContentList.
|
Errors
The OrderDiscount pipeline component writes error messages to the _Basket_Errors collection. The component uses a MessageManager object to retrieve user warning message text.
Constant |
Condition |
|---|---|
pur_discount_removed |
A discount no longer applies since the pipeline was last run. |
pur_discount_changed |
A discount has changed since the pipeline was last run. |
Remarks
The OrderDiscount pipeline component applies discounts to the shopping basket of a user. Each discount is a campaign item and has a unique campaign item ID.
You can adjust the scores of discounts that the OrderDiscount pipeline component applies by using the CSFScoreDiscounts component in a Content Selection pipeline. The CSFScoreDiscounts component adjusts the scores of discounts and saves them in the ContentList object held by the CacheManager object. That ContentList object would then be used by the OrderDiscount pipeline component in another pipeline.
The OrderDiscount pipeline component rounds at the line item level. If more than one discount applies to a line item, the discounts are combined before rounding is finished. Currencies with four decimal places of precision are the exception. In this case, values are truncated to four decimal places as discounts are combined.
For a detailed discussion about how discounts are selected and applied, see Discount Objects.
The _winners and _event keys are used to record events for tracking in the campaign system and are imported into the Data Warehouse for reporting.