[ic] Did you know about Levies? (part of a series)
Mike Heins
mike at perusion.com
Sun Jun 5 09:13:23 EDT 2005
Most users who use Interchange for ecommerce have set up salestax and
shipping. For many applications, that is all that is needed. But some
countries, such as Canada, and some businesses, such as ticket agencies,
have different needs.
Did you know that the Interchange Levies facility is a way to coordinate
and combine separate taxes and fees?
Levies are a way of defining multiple additional product charging such
as taxes, handling, fees, and shipping. If you use Levies, the normal
salestax, shipping, and handling tags are ignored (even when you use the
[assign] tag).
Levy charges are placed into the equivalent of an Interchange shopping
cart, and are unlimited in number.
The "Levy" directive is used to define what the charges are.
The "Levies" directive is used to determine which levies
will be used.
The below definition emulates a standard Interchange setup with only
salestax and shipping:
Levies salestax shipping
Levy salestax description "Sales Tax (%s)"
Levy salestax keep_if_zero 1
Levy salestax type salestax
Levy salestax sort 002
Levy shipping keep_if_zero 1
Levy shipping type shipping
Levy shipping mode_variable mv_shipmode
Levy shipping mode USPS
The actual levies structure looks just like an Interchange shopping cart
-- an array of hashes, with each Levy being a hash. The name of the levy
is in the "code" member, and the various other values (description,
cost, etc.) are other members in the hash.
One might look like:
[
{
code => 'salestax',
description => 'Sales Tax (OH)',
type => 'salestax',
cost => 2.33,
mode => undef,
sort => '010',
part_number => 'SALESTAX',
label => 'Tax',
group => 'salestax',
},
{
code => 'shipping',
description => 'UPS Ground Shipping',
type => 'shipping',
cost => 9.18,
mode => undef,
sort => '020',
part_number => 'SHIPPING',
label => 'Shipping',
group => 'shipping',
},
]
You access the levies cart with [levy-list] LIST [/levy-list]. The
behavior of the list is exactly the same as with an [item-list] for a
shopping cart -- [levy-param description] will access the "description"
member of the hash for that levy.
Levies are a bit processor-intensive, and as such are not recalculated
every time they are accessed. They can be automatically recalculated by
using the "check_status" Levy parameter as described below.
Levies example
Here is a common usage -- GST and PST taxing for Canada, with salestax
calculation for the United States. The standard shipping configuration
is included as well.
Levy gst description GST
Levy gst label GST
Levy gst part_number GST
Levy gst tax_type GST
Levy gst include_if "[if value country eq CA]1[/if]"
Levy gst keep_if_zero 1
Levy gst type salestax
Levy gst sort 002
Levy pst description "PST (%s)"
Levy pst label PST
Levy pst part_number PST
Levy pst tax_type PST
Levy pst include_if "[if value country eq CA]1[/if]"
Levy pst keep_if_zero 1
Levy pst type salestax
Levy pst sort 003
Levy salestax description "Sales Tax (%s)"
Levy salestax label "Tax"
Levy salestax part_number SALESTAX
Levy salestax include_if "[if value country eq US]1[/if]"
Levy salestax keep_if_zero 1
Levy salestax type salestax
Levy salestax sort 002
Levy shipping label "Shipping"
Levy shipping type shipping
Levy shipping part_number SHIPPING
Levy shipping mode_from_values mv_shipmode
Levy shipping check_status mv_shipmode
Levy shipping group shipping
The above will work well if you have the various Canadian province
taxes defined in the "state" table as multiple entries (as shown in the
"standard" demo).
code country state name tax tax_name
00185 CA AB Alberta 7% PST
00187 CA MB Manitoba 8% GST
00039 CA AB Alberta 8% GST
00041 CA MB Manitoba 6% PST
Here is the section in the "standard" catalog ord/finalize page
that calls out Levies for display:
[if config Levies]
[levies recalculate=1 hide=1]
[levy-list]
<tr>
<td align=left class=contentbar1>[levy-param label]:</TD>
<td align=right class=contentbar1>[levy-param cost]</TD>
</tr>
[/levy-list]
[else]
You can see that in this case, if the order is from Canada, you will
get something like:
<tr>
<td align=left class=contentbar1>GST:</TD>
<td align=right class=contentbar1>2.44</TD>
</tr>
<tr>
<td align=left class=contentbar1>PST (AB):</TD>
<td align=right class=contentbar1>2.13</TD>
</tr>
<tr>
<td align=left class=contentbar1>Shipping:</TD>
<td align=right class=contentbar1>7.35</TD>
</tr>
Levies Directives for Configuration
There are two "catalog.cfg" directives for levies -- "Levies"
and "Levy".
The "Levies" directive is a simple list of symbolic names --
though we use *salestax* and *shipping* above, they could be called
"foo" and "bar". They are just identifiers to call out which "Levy"
sections will be applied.
The "Levy" directive is an Interchange locale-style
directive, with an unlimited number of keys that can be set in different
areas. Each Levy type has a number of settings which can be used.
add_to
Indicates that the result of this levy should be added to another
levy for purposes of display and summarization.
check_status
The names of Interchange Values members that should be checked to
see if a Levy needs to be recalculated. This is commonly set to
"mv_shipmode" for the shipping types, as any time that value changes
the levy cart will need to be recalculated.
description
The string that is shown when [levy-param description] is used.
exclude_if
The levy is excluded from calculations if this parameter evaluates
to true (in the Perl sense).
There are three possible ways to use it:
* If a single word with only word characters, like *no_salestax*,
the levy is ignored when that member of Values is set. For
instance:
# catalog.cfg entry
# Don't tax our resellers
Levy salestax exclude_if tax_id
If the customer has put in a tax_id value, the "salestax" levy
will be excluded.
* If it contains ITL code (a __VARIABLE__ or ITL tag) it will be
interpreted as ITL and be true when that returns a true value.
(A whitespace-only return will not be true.)
* If it is neither of the above, it is read as embedded Perl and
will be true if that code segment returns true.
free_message
If the levy has "keep_if_zero" in ic_ecommerce set, and you wish to
display a message when the cost is zero, set it in this.
group
Defines a group so that you can pull out and summarize all items in
that group. If you have two levies, "gst" and "pst", which are
defined as salestax, then [levies group=salestax] will return the
combined cost of those.
include_if
Levy is not included unless the condition in "include_if" pertains.
The behavior is the same as "exclude_if" except for the sense.
inclusive
Indicates that the item is included in the price. In other words,
with VAT, this value is only maintained for display purposes and is
not added to [subtotal] to get [total-cost].
keep_if_zero
Indicates the item should be kept in the levies cart for display
even if its value is zero.
label_value
The Interchange Values member which should be read to get a value to
substitute in the description.
Levy salestax description Sales Tax (%s)
Levy salestax label_value state
If the customer has a state value of "OH", the above will result in
a levy description of Sales Tax (OH).
mode
The mode which should be used for the levy if it is a "shipping"
type.
mode_from_scratch
An Interchange Scratch member/key which is used to set the mode.
mode_from_values
An Interchange Values member/key which is used to set the mode. This
is commonly used to set the shipping mode from the value
"mv_shipmode" in icvariables.
multi
Indicates that this levy uses the "Salestax multi" behavior and
calculates tax from the country and state tables. (Described above).
part_number
A part number which can be passed to an accounting program which
uses part numbers to pass tax and shipping, QuickBooks being an
example.
sort
The order in which the item should be displayed in the [levy-list].
Compared in string context, so 011 will come before 1.
tax_fields
This is the same as the catalog.cfg directive "SalesTax",
and sets the Values fields used to do a simple salestax
lookup. A typical value would be "state" or "zip, state".
tax_type
A tax type to be passed to the "multi" calculation, perhaps for
calculating GST and PST separately.
type
One of "salestax", "shipping", or "custom". The default is
"shipping" unless the mode name is "salestax".
The three types:
salestax
Uses the Interchange salestax routines as the method of
calculation.
shipping
Uses the Interchange shipping routines as the method of
calculation.
handling
Uses the Interchange shipping routines as the method of
calculation, but by default is sorted later than "shipping" in
the levy cart,
custom
The name of a Sub or GlobalSub which will return the cost of the
levy.
--
Mike Heins
Perusion -- Expert Interchange Consulting http://www.perusion.com/
phone +1.765.647.1295 tollfree 800-949-1889 <mike at perusion.com>
Fast, reliable, cheap. Pick two and we'll talk. -- unknown
More information about the interchange-users
mailing list