OrderDiscount (PCR)
For the latest version of Commerce Server 2007 Help, see the Microsoft Web site.

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:

  • Conditions: ITEM_SORT_CONDITION_AND_AWARD_LAST

  • Awards: ITEM_SORT_CONDITION_AND_AWARD_LAST (the other options are ITEM_SORT_PQBI and ITEM_SORT_PRICE_INCREASE)

The Awards sort order can be changed on the OrderDiscount property page UI.

There are three sorts used by the OrderDiscount engine:

  • ITEM_SORT_PQBI: Sort decreasing by price first, decreasing by quantity second, and increasing by basket index third.

  • ITEM_SORT_CONDITION_AND_AWARD_LAST: Items that are in BOTH the condition set and award are sorted to the end (used last). Otherwise follows the PQBI sort defined earlier.

  • ITEM_SORT_PRICE_INCREASE: Sort increasing by price first, decreasing by quantity second, and increasing by basket index third.

To modify the condition sort:

  • Replace the stored procedure that is used by CSFLoadDiscounts with a customized version that includes a “condition_sort” column.

or:

  • Add a column to the discount cache (ContentListFactory object) called condition_sort. If condition_sort is present, it will override the default. The valid condition_sort values are as follows:

    ITEM_SORT_PQBI = 0

    ITEM_SORT_CONDITION_AND_AWARD_LAST = 2

    ITEM_SORT_PQBI_PRICE_INCREASE = 3

To modify the award sort:

  • The method to change the award sort resembles the condition sort. Replace the stored procedure with a customized version that includes an “award_sort” column.

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)

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:

  • discount_id: Campaign item ID (VT_I4)

  • discount_priority: Discount priority (rank) (VT_I4)

  • discount_timestamp: Last-modified timestamp of the discount (VT_DATE)

  • cy_discount_amount: How much was actually taken off the item (VT_CY)

  • discount_type: 1=Currency value; 2=Percentage (VT_I4)

  • cy_discount_value: Currency value or percentage value (VT_CY)

  • discount_name: Discount name (VT_BSTR)

  • discount_basket_display: The name of the discount suitable for displaying to the user. If the Language key of the Context dictionary has a value, the value is used to look up the string to use for the value of the discount_basket_display element. If the Language key of the Context dictionary does not have a value, the value of the discount_basket_display element is in the default language of the Marketing system. (VT_BSTR)

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:

  • discount_id: Integer (VT_I4)

  • discount_timestamp: Last-modified timestamp of the discount (VT_DATE)

  • discount_name: Discount name (VT_BSTR)

  • discount_basket_display: The name of the discount suitable for displaying to the user. If the Language key of the Context dictionary has a value, the value is used to look up the string to use for the value of the discount_basket_display element. If the Language key of the Context dictionary does not have a value, the value of the discount_basket_display element is in the default language of the Marketing system. (VT_BSTR)

The following are the dictionary entries if the element represents a combined percentage-off discount:

  • discounts_combined: A SimpleList object that describes each discount that was combined. Each element in this list is a dictionary with the following keys:

    • discount_id: Integer (VT_I4)

    • cy_discount_percentage: Value (VT_CY)

    • discount_timestamp: Last-modified timestamp of the discount (VT_DATE)

    • discount_name: Discount name (VT_BSTR)

    • discount_basket_display: The name of the discount suitable for displaying to the user. If the Language key of the Context dictionary has a value, the value is used to look up the string to use for the value of the discount_basket_display element. If the Language key of the Context dictionary does not have a value, the value of the discount_basket_display element is in the default language of the Marketing system. (VT_BSTR)

The following are the dictionary entries that exist in both cases:

  • discount_priority: Priority (rank).

  • discount_type: 1=Currency; 2=Percentage (VT_I4).

  • cy_discount_value: Currency or Percentage value (VT_CY). If the element represents a combined percentage-off discount, this is the total percentage.

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:

  • 1 (money discount)

  • 2 (percentage discount)

More than one type of order level discount may apply to the same OrderForm.

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>_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.
See Also

Other Resources

Discount Objects
CSFLoadDiscounts
CSFScoreDiscounts
Page view tracker