OrderDiscount

Article
11/12/2009

Use this component to apply discounts scheduled in the Campaign Manager module in Commerce Server Business Desk 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.

Click Apply to save your changes.

For more information about discount interactions, see Order Subtotal Discount.

Configuration Values

None.

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 containing the IDs of the discounts that applied to this line item the last time the OrderDiscount pipeline compoenent was run. Keys are the IDs; values are the date/timestamps of the discounts. This is normally persisted with the OrderForm object 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). The last-modified timestamp is the time the discount campaign item was last modified in Business Desk.
`discounts_clicked`	Order	Optional. The campaign item IDs of the click-required discounts that have been clicked. Type: SimpleList of Integer
`_discounts`	Order	Optional (if null, the CacheManager and CacheName objects are used to retrieve the ContentList object of discounts from the cache automatically). A ContentList object that contains the cached list of discounts that attempt to apply to the OrderForm object. Discounts may be prefiltered from the list by setting their score property to zero. Type: Currency Note Internally, the ActiveRows property is used to retrieve only the unfiltered discounts from the list. Therefore, the Threshold property of the ContentList object, along with each score property of the content item, can be used to control the set of discounts eligible for application for each individual request.
`orderlevel_discounts_applied`	Order	Optional. A dictionary with information about the discounts that were applied at the order level the previous time the OrderDiscount component was run. It is normally persisted along with the OrderForm object 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) Notes The format of the dictionary is a mapping from discount ID (campaign item ID) to a last-modified timestamp (VT_DATE). The last-modified timestamp is the time the discount campaign item was last modified in Business Desk. This dictionary should not be used for accounting systems.
`_currency_decimal_places`	Order	Optional (if not set, the `_currency_lcid` key must be set, and the number of currency decimal places will be the default for that locale). Describes the number of digits of precision (after the decimal point) from which to round certain intermediate results, and to round to when writing currency values into the OrderForm object. Type: Integer (VT_I4)
`_currency_lcid`	Order	Optional (required only if the `_currency_decimal_places` key is not set). Describes a locale (LCID) from which to retrieve the number of currency decimal places. Type: Integer (VT_I4)
`Evaluator`	Context	Required. The expression evaluator instance used to evaluate product, targeting context, and user expressions. Type: IExprEval (VT_DISPATCH)
`_trace_discounts`	Context	Optional (default is false). Determines whether the OrderDiscount component should generate tracing information. Type: Bool (VT_BOOL) Notes 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. When enabled, the key `_discounts_trace_info` will be written to the OrderForm object.
`CacheManager`	Context	Optional (unless the `_discounts` key was not set in the OrderForm object). A CacheManager object 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 OrderForm object). The name of the CacheManager cache containing the cached set of discounts Type: String (VT_BSTR)
`MessageManager`	Context	Required (only checked if one of the warnings listed under Notes is used). A reference to a MessageManager object. Type: IMSCSMessageManager_3_0 (VT_DISPATCH) Notes The following messages may be added to the `_Basket_Errors` list in the OrderForm object: `pur_discount_removed` (one or more discounts no longer apply). `pur_discount_changed` (one or more discounts have changed).
`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)
`UserProfile`	Context	Optional. A ProfileObject object representing the current user, which 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, which 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 containing the discounts from the discounts cache, which 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, which 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), normally in the Accept stage of the checkout pipeline.
`_event`	Always written. Contains the name of the event to record, which 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), normally in the Accept stage of the checkout pipeline.
`item._itemlevel_discounts_applied`	Not always written (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 of 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) 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)
`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`	Not always written. A dictionary containing 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 normally persisted along with the OrderForm object 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). The last-modified timestamp is the time the discount campaign item was last modified in Business Desk.
`_discounts_removed`	Not always written. A SimpleList object, which contains campaign item IDs of discounts that no longer apply to the basket since the last time 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`	Not always written. A SimpleList object, which contains campaign item IDs of discounts that have changed since the last time 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.
`orderlevel_discounts_applied`	Not always written (written only if one or more order level discounts were applied). A dictionary with information about the discounts that applied at the order level the last time the OrderDiscount component was run. This is normally persisted along with the OrderForm object 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). The last-modified timestamp is the time the discount campaign item was last modified in Business Desk.
`_orderlevel_discounts_detail`	Not always written (written only if one or more order level discounts were applied). A dictionary that maps special offer types to a list of order level discounts that applies for that special offer type. 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. 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) Following are the dictionary entries if the element represents a combined percentage-off discount: `discounts_combined`: A SimpleList object that describes each of the discounts that were 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`: Llast_modified tiemestamp of the discount (VT_DATE) `discount_name`: Discount name (VT_BSTR) 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 greater than 100 percent, even if the sum of the percentages of discounts in the discounts_combined list is greater than 100. The last contribution of the discount is considered as the only amount that will apply. If the combination is already discounted 100 percent, no further 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.
`_Basket_Errors`	Not always written (modified if `_discounts_removed` or `discounts_changed` is set). Error messages are written to this SimpleList object. Type: IsimpleList (VT_DISPATCH) Note Every OrderForm object has a `_Basket_Errors` list that is used to report non-fatal pipline errors to the user.
`_qualifying_discounts`	Not always written (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`	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`	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: 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 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`	Not always written. 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 of 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 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`	Not always written. 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 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 get the item IDs. It can then look up the discount descriptions from the `_discounts ContentList`.

Errors

The 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 component applies discounts to the shopping basket of a user. The discounts are scheduled through the Campaign Manager module in Commerce Server Business Desk. Each discount is a campaign item and has a unique campaign item ID.

You can adjust the scores of discounts that the OrderDiscount component applies by using the ScoreDiscounts component in a Content Selection pipeline. The ScoreDiscounts 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 component in another pipeline.

The OrderDiscount component rounds at the line item level — if more than one discount applies to a line item, the discounts are combined before rounding is done. 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.