Price maintenance with CommonAdjust

Introduction

The CommonAdjust directive allows you to implement a flexible chained pricing scheme.  Prices can be adjusted based upon the quantity of items in the cart, by attribute value, with a table lookup, with a call to Interchange tags or UserTags or even with a block of Perl code.

Different CommonAdjust directive settings can be specified for different classes of logged-in user, depending upon defined user Profiles.

General rules

This section lists the five simple rules that are followed by CommonAdjust when calculating a price value.

Rule 1

If CommonAdjust is set to any value, valid or not, extended price adjustments are enabled.  It may also hold the default pricing scheme.

Rule 2

The item's PriceField column may also hold a CommonAdjust atom string, which takes precedence over the default.

Rule 3

If CommonAdjust directive is set, and the item's PriceField column is empty (or specifically 0), then it will be used to set the price of the item.

Rule 4

If no CommonAdjust atoms are found, then the price will be zero, subject to any later discounts.

Rule 5

If another CommonAdjust atom is found as the result of an operation, it will be re-parsed and the result applied.  Chaining is retained;  a fall-back may be passed and will take effect.

Price adjustments

Prices may be adjusted in several ways, and the individual actions are referred to atoms.  Price atoms may be final, chained, or fallback.  A final atom is always applied if it does not evaluate to zero.  A chained atom is subject to further adjustment.  A fallback atom is skipped if a previous chained price was not zero.

Atoms are separated by whitespace, and may be quoted (although there should not normally be whitespace in a setting).  A chained atom ends with a comma.  A fallback atom has a leading semi-colon.  Final atoms have no comma appended or semi-colon prepended.

A setter is the means by which the price is set.  There are eight different types of price setters.  All setters can then yield another CommonAdjust atom.

It is quite possible to create endless loops, so the maximum number of initial CommonAdjust atoms is set to 16, and there may be only 32 iterations by default before the price will return zero on an error.  The maximum number of iterations can be overridden with the Limit directive's "chained_cost_levels" setting.

Atom syntax

Optional atoms, below, have an asterisk appended.  The asterisk should not be used in the actual string.  An optional table always defaults to the active ProductFiles table(s).  The optional table key defaults to the item code, except in a special case for the attribute-based lookup.  The field name is not optional except in the case of an attribute lookup.

N.NN or -N.NN

Where N is a digit.  A number which is applied as an adjustment to the current price value.  For instance, if the price is 10 and -2 is applied, then the next price value will be 8.  The value be a positive or negative number.

N.NN%

Where N is a digit.  A number which is applied as a percentage of the current price value.  May be a positive or negative number.  For example, if the price is 10, and -8% is applied, then the next price value will be 9.20.

table:column:key

Causes a straight lookup in a database table.  The optional "table" name defaults to the main ProductFiles table(s) for the item.  The column must always be present.  The optional key defaults to the item code, except in a special case for the attribute-based lookup.  The return value is then re-parsed as another atom.

table:col1..col5,col10:key

Causes a quantity lookup in the named database "table", which defaults to the ProductFiles table(s), with a set of comma-separated fields looked up by the optional key.  The optional key defaults to the item code.  If ranges are specified with "..", each column in the sequence will be used.  For instance:

is the same as

Leading non-digits are stripped and the item quantity is compared with the numerical portion of the column name.  The price is set to the value of the table's column (numeric portion) that is at least equal to it but doesn't yet reach the next price break.

Warning If the field at the appropriate quantity level is blank, a zero cost will be returned from the atom.  It is important that you either populate all columns with a non-zero, non-blank values or you define a fallback atom.  See quantity pricing.

This atom can also be used to implement a "mix and match" quantity pricing scheme, where the quantity of all items in the named price group are taken into account when determining which of the price breaks to use.

==attribute:table:column:key

Does an attribute-based adjustment.  The attribute is looked up in the named "table", which defaults to the ProductFiles table(s), with the optional column defaulting to the same name as the value of the attribute.  If the "key" is blank and the "column" is not blank then the "key" will default to the value of the attribute.

& CODE

The leading "&" symbol is stripped and the code is passed to the equivalent of a [calcn] tag.  No Interchange tags may be used unless called using "$Tag->tagname()".

The current value of the price and quantity will be available as $s and $q, respectively, and the current item (code, quantity and any attributes) will be available in a hashref named $item.  All of these variables will be forced to the Vend::Interpolate namespace.

The $item hashref will contain at least the following keys:

Name	Description
$item	Reference to the current item's hash.
$item->{code}	The current item's SKU code
$item->{quantity}	Quantity of the current item placed in the cart.
$item->{mv_ib}	The name of the table in which this item can be found.

User defined attributes can also be found in the $item hashref.  For instance, the "colour" attribute (if defined) could be found using $item->{colour}.

[Interchange-tag] or __VARIABLE__

If the atom begins with a square bracket ([) or an underscore (_), it will be parsed for Interchange tags and variables (but with no Locale-related substitution).  One use for this is to make use of a price defined in a Variable.  Another would be to call a custom UserTag.  The value returned by the tag or Variable will be re-submitted as an atom, so that it may yield yet another setter.

The current value of the price and quantity will be available to UserTags as $s and $q, respectively, and the current item (code, quantity and any attributes) will be available in a hashref named $item.  All of these variables will be forced to the Vend::Interpolate namespace.  See the "& CODE" atom description for more information about the "$item" hashref.

$

Tells Interchange to look in the mv_price attribute in the item's row in the current shopping cart and, if it exists, to apply that price as the final price.  The attribute must be a numerical value.

>>word

Tells the routine to return the word directly as the result.  This is not useful in pricing, as it will evaluate to zero.  But when CommonAdjust is used for shipping, it is a way of re-directing shipping modes.

word

The word value , which must not match any of the other atoms, is made available as a key for the next lookup (only).  If the next atom is a database lookup, and it contains a dollar sign ($) then the word will be substituted (i.e. "table:column:$" will become "table:column:word").

(setter)

The word returned returned by setter will be used as a key for the next lookup (only).  If the next atom is a database lookup, and it contains a dollar sign ($) then the word will be substituted (i.e. "table:column:$" will become "table:column:word").

Examples

Most of the following examples use a table called "pricing".  This is not a hard-coded requirement;  Any valid table, including the ProductFiles table(s) may be used instead.

The examples in this section will refer to the following pricing table:

sku	common	price_group	q5	q10	q25	XL	S	red
99-102			9	8	7	1	-0.50	0.75
00-343						2
00-0010		group_a	10	9	8
00-0020		group_a	20	18	17
red	0.75

Adjusting an item price based on an attribute

The simplest case is a straight lookup on an attribute.  Size, in the following example:

With this value in the price column, a base price of 10.00 will be adjusted with the value of the size attribute.  If size for the item 99-102 is set to XL then 1.00 will be added to make a total price of 11.00.  If the size is S then 0.50 will be subtracted to make a total price of 9.50 For any other size value, no further adjustment would be made.  Item code 00-343 would be adjusted up 2.00 only for XL.

Adjusting an item price based on more than one attribute

Let's say we had an item from previous example, and we wanted to define a pricing adjustment based on the colour attribute as well as the size.

This is the same as the previous example, except that both size and colour are adjusted for.  A colour value of red for item code 99-102 would add 0.75 to the price.  Item 00-343 would not be affected by the colour.

Adjusting the price based upon a common value

Here, price is set based on a common column, keyed by the value of the colour attribute.  Any item with a colour value of red would have 0.75 added to the base price.

Quantity pricing

Here is a quantity price lookup, with a fallback price setting.  If there is a valid price found at a quantity of 1, 5 or 10, depending upon the item quantity, then it will be used.  The fall-back of 10.00 only applies if no non-zero and non-blank price was found in the quantity lookup.  In either case, the size and colour adjustment is applied.

Removing the comma from the end of the fallback string stops the colour/size lookup if it reaches that point.  If a quantity price was found, then size and colour are chained.

The value of the list_price column is used as a fallback, instead of the fixed 10.00 value.  The above value might be a nice one to use as the default for a typical retail website that has products defined with differing colours and sizes.

"Mix and match" quantity pricing

You can add the quantities of different items together to determine the price break.

For instance, with the above example, the price for ten "00-0010" items would be $9.00 each, as usual.  If you add three "00-0020" items to the cart, then those items will all be priced at $18.00 each.  This is because both of the SKUs are members of the same "price_group", and so the quantities are summed to determine the price break.

If you now add five "99-102" items to the cart then, as those items are not a member of the same "price_group" the "q5" price break will be used for those items.  The 13 "00-0010" and "00-0020" items will continue to use the "q10" price break, of course.

Category:  Interchange ecommerce functions

Last modified by: Kevin Walsh Modification date: Tuesday 29 April 2008 at 5:18 PM (EDT)