AsecureCart.Net works by
interpretting special HTML tags embedded in your own web pages. The following
list the HTML element names that have special meaning to ASecureCart.Net.
"ID" is required. This is the
identifier of the item. It can be the Model Number or any Identifier for the
item. Each ID must be unique for the cart engine to identify each product. ID
values can be hidden from the customer via the Profile Manager so they need not
be long, descriptive names, etc. The maximum allowed size for an ID value is 30
characters. Values should contain just enough information to
uniquely identify each of your products such as the products part number.
Ex. PART-201-A, PART-201-B, etc.:
Tip - Do not use quote marks (") or within the Value unless the value is
enclosed in a single quote ('). Otherwise, your html will be improperly
formatted. For example:
Tip - Use the "Describe" tag (below) to specify long, descriptive text for the product.
Uncheck the "Always Show ID" box on the "Display" screen of the Profile Manager to hide the ID
value from the web receipt (e-mail receipts always show the ID).
"Describe" is optional and will
describe the Product. This value will be displayed to the user in their basket.
<input
Type="hidden" Name="Describe" Value="Deluxe Sparkling Widget">
You can also optionally include an image in the "Describe" field by referencing the URL of the image
and it's height and width attributes. To specify an image for the item, use the ^ character to
separate the description from the image URL. The image URL must be an absolute URL (i.e. - it must begin
with http:// or https://). The syntax for including an
image is:
"description^image_url^height^width"
The height and width parameters are also optional so you can either explicitly specify the image size
or let the browser use the actual size of the image. An example would be:
Note - Once the cart has been posted to the server, the cart will automatically switch to HTTPS mode
when recalculating and some browsers (like Internet Explorer 6.0) will prompt the user that the page
contains both secure and un-secure elements. This is not a problem but it could be an annoyance to
the shopper unless their browser is configured to allow mixed content. You can upload thumbnail images to your area of
the Profile Manager via the "Upload..." button in the "Display" screen. This will allow the browser to reference your thumbnail images
securely along with the rest of the cart page.
"Qty" is optional and will
contain the default quantity for the item. If a "Qty" element is not provided
or is not a positive integer value, the cart engine will default to "1" for new
items. Therefore, you only need it if your default quantity is different than
1.
Like all fields, you can provide "Qty" as a hidden field or as an input field.
Here is an example of a hidden field that would override the default to order
by the dozen:
<input Type="hidden"
Name="Qty" Value="12">
Alternatively, you could use "Qty" as an input box to allow users to order any
number that they desire. Here is the input field code:
<input Type="text"
Size="3" Name="Qty" Value="">
which would create this
Tip - Use the QtyMin, QtyMax, and QtyMultiples tags to further define values
that the user is allowed to order.
Tip - The cart remembers the quantity of each item ordered. If the cart
captures a quantity and later the user presses the submit button for the same
item, it will keep the previous value unless the user explicitly enters a new
number. This is to prevent shoppers from accidently changing their quantities
after entering them.
"QtyMin" is an optional value
that will not allow the cart to check out if the "Qty" value is less than this
value. If QtyMin is not specified or a non-numeric value, no minimum check is
applied.
Here is an example of a hidden field "QtyMin" value of "10":
<input Type="hidden"
Name="QtyMin" Value="10">
Please note that the QtyMin value is only checked when the user has submitted
the item to the cart server. You would need to add Javascript code in your web
page to restrict the Qty value in the client's browser prior to submitting the
item.
Tip - Click here for using advanced modifier options
for setting a "QtyMin" value.
"QtyMax" is an optional value
that will not allow the cart to check out if the "Qty" value is greater than
this value. If QtyMax is not specified or a non-numeric value, no maximum
quantity check is applied.
Here is an example of a hidden field "QtyMax" value of "100":
<input Type="hidden"
Name="QtyMax" Value="100">
Please note that the QtyMax value is only checked when the user has submitted
the item to the cart server. You would need to add Javascript code in your web
page to restrict the Qty value in the client's browser prior to submitting the
item.
Tip - Click here for using advanced modifier options
for setting a "QtyMax" value.
"QtyMultiples" is an optional
value that will not allow the cart to check out if the "Qty" value is not a
multiple of this value. If QtyMultiples is not specified or a non-numeric
value, no multiple check is applied.
Here is an example of a hidden field "QtyMultiples" value of "5":
<input Type="hidden"
Name="QtyMultiples" Value="5">
Please note that the QtyMultiples value is only checked when the user has
submitted the item to the cart server. You would need to add Javascript code in
your web page to restrict the Qty value in the client's browser prior to
submitting the item.
Tip - Click here for using advanced modifier options
for setting a "QtyMultiples" value.
"Price" is optional and
specifies the unit price of the item. If not specified or a non-numeric value,
then the price will be set to zero for that item.
<input type="hidden"
Name="Price" Value="49.50">
Sometimes you may want to leave the price at zero and use the "AddOn",
"NAddOn", "Size", or "Color"
tags to determine the price.
"Multi" is an optional value
that can be used if you want to allow the same item to be added to the cart
more then one time based on different options like Color, Size, or the Addon fields.
"Multi" supports two values "Y" for yes and "N" for no. These values are not
case sensitive, so "Y" and "y" are equivalent, as are "N" and "n".
When set to "Y", the shopper can select the same item multiple times with
different options, such as 2 large red, 3 small green, and 5 medium blue items.
When set to "N" or not specified, the cart will overwrite the item based on its
ID value.
<input type="hidden"
Name="Multi" Value="Y">
"Size" is an optional value. You
have the option to add additional charges for each size if you wish using the
format "value^price". For example, if you wanted to include an
additional price for large and extra large sizes, you would use the "Price"
element to set the base price and then use the following to modify the price
according to the size selected:
<input type="hidden"
Name="Price" Value="19.95">
An equivalent method would let the "Size" dropdown determine the entire price
by not defining a base price and adding a ^price modifier to each item
in the dropdown list, such as:
<input type="hidden"
Name="Price" Value="0">
Note - Price modifiers must be numeric values. Also, if "Multi" is set to "Y"
then the cart will keep adding items to the cart of different combinations,
allowing the user to order a Small, two Mediums, and an X-Large, etc.
Tip - Click here for advanced Size modifier options.
Tip - To make an AddOn, Size, Price, or Color field required, preface the field name with the tilde (~) character. E.g.:
Enter your Size: <input type=text name="~Size" value="">
If the shopper doesn't enter a Size, the cart will report that a required field is missing.
"Color" is an optional value.
You have the option to add additional charges for each color if you wish using
the format "value^price". For example, if you wanted to modify the base
price for different colors in a dropdown list, you would use the "Price"
element to set the base price and then use the following to modify the price
according to the color selected:
<input type="hidden"
Name="Price" Value="12.50">
An equivalent method would let the "Color" dropdown determine the entire price
by not defining a base price and adding a ^price modifier to each item
in the dropdown list, such as:
<input type="hidden"
Name="Price" Value="0">
Note - Price modifiers must be numeric values. Also, if "Multi" is set to "Y"
then the cart will keep adding items to the cart of different combinations,
allowing the user to order a White item, three Purple items, etc.
Tip - Click here for advanced Color modifier options
Tip - To make an AddOn, Size, Price, or Color field required, preface the field name with the tilde (~) character. E.g.:
Enter your color code: <input type=text name="~Color" value="">
If the shopper doesn't enter a color, the cart will report that a required field is missing.
The AddOn values give you the
ability to add more options and extra charges if you wish. They behave similiar
to "Color" and "Size" but you can define the type of modifier that meets your
product line needs. For example,
<select name="AddOn1">
<option value="Model - Base">Base Model
<option value="Model - Deluxe^25.00">Deluxe Version - Add
$25.00
<option value="Model - Premium^50.00">Premium Version - Add
$50.00
</select>
Note - Price modifiers must be numeric values. Also, if "Multi" is set to "Y"
then the cart will keep adding items to the cart of different combinations,
allowing the user to order a Base Model, two Deluxe Versions, etc.
Tip - Click here for advanced AddOn modifier options
Tip - To make an AddOn, Size, Price, or Color field required, preface the field name with the tilde (~) character. E.g.:
Enter your value: <input type=text name="~AddOn1" value="">
If the shopper doesn't enter a value, the cart will report that a required field is missing.
NAddOns are "No Multi AddOn's".
These will prevent another item from being added to the cart if these options
are already selected. For example, to allow the user to select multiple items
and optionally include an additional instructional video, use:
<input name="NAddOn1"
type="checkbox" value="Learning Video^5.00">With Learning Video Tape - Add
$5.00
Note - Multi=N will always overwrite the item in the cart no matter which
options they choose.
Tip - Click here for advanced NAddOn modifier options
Using "DiscStr", you can build
price breaks on each product based on quantity purchased.
"DiscStr" works by creating a hidden variable that lists the quantity and price
breaks using the format min,max,price. For example:
<input type="hidden"
name="DiscStr" value="1,5,10.95;6,10,8.95;11,20,5.95;21,100,2.95">
The above example would mean:
1 - 5 for $10.95
6 - 10 for $8.95
11 - 20 for $5.95
Over 20 for $2.95
The last qty number is 100. This can be any number because if it's not on the
table, it will use the last price it finds. It will use 2.95 for any quantity
21 and over in this example.
Tip - You can define global discounts for your products in the Profile Manager
under Global Discounts.
By default, any discounts and/or
coupons will be applied to all items that the shopper adds to their cart. Use
"DiscItem" if you want to exclude specific items from being discounted.
"DiscItem" is an optional value and supports two values - "Y" for yes and "N"
for no. These values are not case sensitive, so "Y" and "y" are equivalent, as
are "N" and "n".
When set to "Y" or not specified, the item will be included when determining
any global or coupon discount amounts.
If set to "N" then the item will not be discounted.
<input type="hidden"
name="DiscItem" value="N">
Tip - Use the "Global Discount" section of the Profile Manager to define global
discounts that are valid for your products.
Tip - Use the "Coupon" section of the Profile Manager to create coupons that
can be used by your shoppers.
"TaxItem" is an optional value
used to determine whether sales tax should be applied to this item.
"TaxItem" supports two values "Y" for yes and "N" for no. These values are not
case sensitive, so "Y" and "y" are equivalent, as are "N" and "n".
When set to "Y" or not specified, sales tax will be added to the item if a
purchase is made within a Tax Regions defined in the Profile Manager under
"Taxes".
If set to "N" then the item will not be charged sales tax. You can mix taxable
and non-taxable items in one basket and the system will calculate accurately
for you.
<input type="hidden"
name="TaxItem" value="N">
"Ship" is an optional value that
contains the shipping price of the item when your Profile Manager Shipping
Option section has specified the Shipping Method to be "By Region". The value
is usually a numeric dollar amount based on a per item calculation.
<input type="hidden"
name="Ship" value="3.00">
However, if you want to define free shipping for an item, you can set the value
to "x".
Shipping Region Description:
When your Shipping Method is "By Region", you define various "regions" in the
Profile Manager under the Shipping Options, Shipping Regions menu item. A
region may be a type of shipping method (such as UPS Ground) or a geographical
location (such as "U.S. lower 48" or "Internet").
Each defined region contains a Primary Minimum, Primary Multiplier, Secondary
Minimum and Secondary Multipiler value. When the shopper selects a "region"
during checkout, the "Ship" value for the item is compared to the region table
to calculate the price.
Example: Let's say that you create a region called "U.S." and the primary
multipler is 1. When a product has a
<input type="hidden" name="Ship" value="3.00">, AsecureCart will
calculate the shipping as 3.00 x 1 X 1 = $3.00 for this region ("Ship" value x
qty * multipler). If the shopper ordered 5 items, the cost would be $15.00 -
3.00 x 5 x 1. If the calculated cost is less than the minimum, the minimum is
used.
Now, let's say you have a "Canada" region with a 1.5 primary multiplier. If the
shopper selects the "Canada" region, for the same item, the shipping rate would
be calculated $3.00 X 1 x 1.5 = $4.50. If this shopper orders five items for
the Canada region, the cost would be $22.50 or $3.00 x 5 x 1.5.
This allows you to create precise and customized shipping rates very easily on
a product-by-product basis. The Secondary Minimum and Secondary Multiplier work
the same way as the Primary values but are only used for products using
<input type="hidden" name="ShipKey" value="S2"> elements (see
ShipKey for details). This allows granular shipping rates for the Shipping
Regions method.
Tip - Click here for using advanced modifier options
for setting a "Ship" value.
"ShipKey" extends the Ship
tag by instructing ASecureCart to a region's Secondary Minimum and Secondary
Multipler values of the "Shipping Entries" or "Shipping Country" screens (or the Secondary "Price/Qty Table" screen when using "By Price" shipping).
The "ShipKey" variable supports a value of "S2".
<input type="hidden"
name="ShipKey" value="S2">
When the "ShipKey" variable is not specified or not set to "S2", the Primary Minimum and Multipler fields (or Primary "Price/Qty Table" screen) will be used when calculating shipping.
If the "ShipKey" variable is set to "S2", cart will use the Secondary Minimum and Multipler fields (or "ShipKey=S2" table for "By Price" shipping).
Note - if you need additional "Price/Qty Table" shipping tables, contact support. ASecureCart Support Personnel can add
additional tables to your account which will allow values of "S3", "S4", etc. for the "ShipKey" variable.
"Weight" is an optional value
that is used when the Profile Manager Shipping Option section has specified the
Shipping Method to be "By Price", "By Qty", or "UPS". Weight contains the
weight of the item. Do NOT include any unit of measurement indicator such as
"lb", "oz", etc. Only numeric values will be applied. Weight values are used
differently when the Shipping Method is set to "UPS" than when Shipping Method
is either "By Price" or "By Qty".
When set to "By Price" or "By Qty", you can base the weight on ounces, pounds,
liters or any units of measurement. When an item has a "Weight" value
specified, ASecureCart will multiply weight x quantity for each item. Next, it
will look in your weight table and determine the price based on the total
weight values of all items. If this total is less than your minimum then it
will use the minimum.
Tip - Be sure your weight table values in the Profile Manager use the same unit
of measurement as the Weight elements used for each item. Otherwise, the
shipping charge will not be calculated correctly.
If your Profile Manager is set to use the "UPS" Shipping Method, Weight MUST be
based on U.S. pounds. When the user enters the Ship To zip code, ASecureCart will
contact UPS in real-time to determine the shipping charge based on the
accumulated weight values and the shipping service selected (Overnight, 2nd
Day, Ground, etc.).
<input type="hidden"
name="Weight" value="16">
Tip - Click here for using advanced modifier options
for setting a "Weight" value.
"Show" is used to determine
whether or not to display the cart checkout page when adding items to the
basket.
When not specified, the complete cart checkout page will be displayed
each time and item is added to the cart.
When set to an absolute URL such as
"http://www.yourcompany.com/mypage.html", the shopper can add items to their cart and the shopper is automatically returned to the same page they
were just on. This allows you to silently add items to the cart without
displaying the complete cart checkout for each item added.
When setting the "Show" variable, you must include the http:// portion in order to re-direct the buyer back to your page.
Using the "Show" variable is particularly useful if displaying a mini-cart within your website. Your customers can
add items to their cart while having the appearance of remaining on your website until they are ready to checkout.
This allows you to limit how
certain items can be shipped. For example, if you have a product that you only
want to ship UPS Ground, you can include a "ShipAllowed" field that contains
"UPS Ground".
If a product has a ShipAllowed defined, the shopper will not be allowed to
check out unless their shipping choice is found in the ShipAllowed field. The
ShipAllowed field is tested against your defined Shipping Regions and/or UPS
services selected (i.e. – either the Shipping Regions page or the UPS Options
page in the Profile Manager). If two products are ordered and only one of them
has a ShipAllowed defined, the ShipAllowed will affect the entire order. Use
commas to separate multiple allowed shipping options, such as:
<input type="hidden"
Name="ShipAllowed" Value="UPS Ground,UPS 3 Day Select">
Caution - if you specify a ShipAllowed value that does not exist as either a
defined Shipping Region or selected UPS Service, the shopper won’t be allowed
to check out. For example, if you only allow "UPS Ground" but don't have "UPS
Ground" as an available Shipping choice, the shopper won't be able to check
out.
When the user adds an item to
their cart, A "Review Item" link will be displayed next to each item in the cart so
the shopper can jump directly to the item from the cart. This value is usually automatically determined
but you can also explicitly set the value by specifying a "ReturnLink" URL. "ReturnLink" values must be
absolute URLs (i.e. -- "http://www.mycompany.com/mypage.aspx"). Relative URLs
(i.e. -- "../mypage.aspx") will not work since the user only sees the link when
displayed on the cart page running on the ASecureCart.Net servers.
<input type="hidden"
Name="ReturnLink" Value="http://www.mycompany.com/mypage.aspx">
You can also optionally include an image in the "ReturnLInk" field by referencing the URL of the image
and it's height and width attributes. To specify an image for the ReturnLink, use the ^ character to
separate the return link URL from the image URL. Like the ReturnLink, the image URL must be an absolute
URL (i.e. - it must begin with http:// or https://). When the image URL is included in the ReturnLink value,
the image is used instead of the words "Review Item". The syntax for including an
image is:
"return_url^image_url^height^width"
The height and width parameters are also optional so you can either explicitly specify the image size
or let the browser use the actual size of the image. An example would be:
Note - Once the cart has been posted to the server, the cart will automatically switch to HTTPS mode
when recalculating and some browsers (like Internet Explorer 6.0) will prompt the user that the page
contains both secure and un-secure elements. This is not a problem but it could be an annoyance to
the shopper unless their browser is configured to allow mixed content. You can also upload thumbnail images to your area of
the Profile Manager via the "Upload..." button in the "Display" screen. This will allow the browser to reference your thumbnail images
securely along with the rest of the cart page.
Related1 through Related5 tags
allow you to create up to 5 URLs per product in your cart. Examples of
"related" links might be suggested add-on products, product data sheets,
particular shipping issues that a product may have, etc. Related links allow
you to provide better service to your shoppers or up-sell products.
The syntax for the "Related" value is "absolute URL^description text^target".
For example, this value will display the text "Also Buy This!" and open the
"mylinkpage.html" page in the current window when clicked.
<input type="hidden"
Name="Related1" Value="http://www.mycompany.com/mylinkedpage.html^Also Buy
This!">
To display a product datasheet .PDF in a new window, you could use:
<input type="hidden"
Name="Related1" Value="http://www.mycompany.com/datasheet.pdf^Specs^_new">
The values must be absolute URLs (i.e. --
"http://www.mycompany.com/mypage.aspx"). Relative URLs (i.e. --
"../mypage.aspx") will not work since the user only sees the link when
displayed on the cart page running on the ASecureCart.Net servers.
Tip - For the "target" portion of the Related value, only include the target
identifier. Don't use "target=_new" since the cart engine inserts the "target"
attribute as necessary.
"SKU" is an optional value that
you can use to reference the ordered items with your inventory system and is
generally a used as a hidden tag, such as:
Sometimes, the SKU number may differ depending upon the options selected, such
as Color, Size, or other option. To accommodate this, you can provide ASecureCart
with a "SKU_Rule". The "SKU_Rule" value determines how ASecureCart will create the
SKU based on the selected options.
The Profile Manager allows you to define a default "SKU_Rule" value on the
"Display" screen. You can also pass in a "SKU_Rule" tag which takes precedence
over the default "SKU_Rule". In other words, if "sku_rule" is passed in as a
form variable, that rule will be used; if not passed in, the default rule
defined in the Profile Manager will be used. This allows a default (site wide)
rule to be defined, but then overridden on a page-by-page basis if desired. The
syntax of "sku_rule" is:
where "variable" can be "Color", "Size", "AddOn", or "NAddOn".
Examples:
<input type="hidden"
name="sku_rule" value="accumulate,Color,Size">
This will append the Color's sku modifier to the "sku" value and then it will
append the Size's sku modifier.
<input type="hidden"
name="sku_rule" value="accumulate,Size,Color">
This will append the Size's sku modifier to the "sku" value and then it will
append the Color's sku modifier.
<input type="hidden"
name="sku_rule" value="accumulate,AddOn,Color,Size">
This will append any AddOn sku modifiers to the "sku", then append the Color's
sku modifier, and finally append the Size's sku modifier.
<input type="hidden"
name="sku_rule" value="overwrite,Color,Size">
This will first assign the discrete "sku" value (if present). Then, it will
overwrite it with the Color's sku modifier (if present) and finally, it will
assign the Size's sku modifier (if present).
Tip - A note about the order of AddOn and NAddOn – they will be added in
ascending order. So, you only need to put "AddOn" in the sku_rule and the
engine will overwrite or append AddOn1, then AddOn2, then AddOn3, etc.
Tip - When a hidden "SKU" tag is defined, that will always be used first. This
allows you to define a base SKU value and update or overwrite it based on the
option modifiers and "sku_rule". To have the option modifier's soley determine
the SKU value, do not define a discrete "SKU" element.
Tip - Click here for using advanced modifier options
for passing a "SKU" value.
Electronic Softgood Delivery (ESD) Links allow you deliver to special link
and password/key information to your customers for purchasing Internet based "soft" goods
such as files or premium web addresses.
Upon authorization of the transaction, the customer e-mail will contain the link that you've
specified as well as any custom instructions and/or password/serial number the customer may need
to access the file/web address.
The "ESD" tag is used to indicate whether or not the cart should look in the Electronic Soft Goods table for a
matching "ID" in order to provide the shopper with the link and access information when the order is finalized.
"ESD" supports two values - "Y" for yes or "N" for no. These
values are not case sensitive, so "Y" and "y" are equivalent, as are "N" and
"n".
When set to "Y", the cart will use the "ID" tag to find a matching item in the Electronic Soft Good table that you
define via the Profile Manager. If a match is found, the link and access information is included in the shopper's
e-mail. The "ID" tag for the item and the "Product ID" field defined in the Profile Manager must match exactly in
order for the link and access information to be provided to the customer. See the "Electronic Softgoods Link" menu
item and Help in the Profile Manager for additional information or check out the ESD code samples via the Help Center page.
When set to "N" or if a match is not found in the Electronic Soft Good table, the shopper is allowed to check out
normally. If no "ESD" tag is defined, the cart will default to "N" and allow the shopper to check out normally.
The Event Items feature of the cart allows you to control the number of items ordered during
a specific time period. This can be useful when the ordered item is a scheduled event, an appointment,
or a reservation. For example, a small bed-n-breakfast with 4 rooms can take reservations for each room
so that no overlaps occur, or a sports team or drama club can sell tickets up to the quantity of seats available.
You determine the allowable time frames by combining "EventStart" and "EventEnd" tags. When the shopper checks out and
an ordered item defines a time frame using the "EventStart" and "EventEnd" tags, the cart will verify that the
quantity ordered is allowed for the time frame.
Use the Profile Manager's "Reservation/Scheduled Events" screen to define an event's "ID" and quantity allowed.
Then, in your HTML you will define the same "ID" value and the "EventStart" and "EventEnd" fields.
When a customer orders items from your web pages with "EventStart" and "EventEnd" tags, the cart will compare the "ID" field in
your HTML with the Product ID field in the "Reservation/Scheduled Events" table. If a match is found the quantity ordered is validated to
make sure the order can proceed for the given time period. See the Reservation and Appointment samples at the
Help Center for a working demonstration.
"EventStart" must be a date value using the format MM-DD-YYYY. You can also include the time component of the event
using the format MM-DD-YYYY HH:NN.
For example, if you were selling tickets to a Christmas pagent that started at 7:00 PM on Christmas Eve, you might use either
of these two date methods to indicate the event's start time:
If the pagent was 90 min. long, the combination of tags might be something like:
<input type="hidden" Name="ID" Value="XMAS">
<input type="hidden" Name="Describe" Value="Christmas Pagent Tickets">
<input type="hidden" Name="EventStart" Value="12-24-2005 7:00 PM">
<input type="hidden" Name="EventEnd" Value="12-24-2005 8:30 PM">
<input type="hidden" Name="Price" Value="8.00">
For situations when the time portion is not critical or items that span multiple days such as a bed-n-breakfast room reservation or a cruise,
the "EventStart" may simply indicate the date of the reservation such as:
<input type="hidden"
Name="EventStart" Value="10-06-2005">
In order for an order's time frame to be tracked for an event, the time frame MUST include both
a starting point and ending point. The starting point is always a date or date+time value using the above
formats. The ending point can either be an explicit date or date+time value. The ending point can also be
derived as a duration based on the starting point. See the EventEnd tag for details on
the event's ending time.
The "EventStart", "EventEnd", and "DurType" tags can also be passed as modifiers.
Tip - Click here for advanced "EventStart", "EventEnd" modifier options.
The "EventEnd" tag is used to determine the end of the
time frame for an event item. See "EventStart" for an overview of reservation/scheduled
event items.
"EventEnd" must be either an explicit date value or a derived date/time value based on the "EventStart" tag.
When defining an explicit date/time, you must use either MM-DD-YYYY or MM-DD-YYYY HH:NN (use the latter if the
time is critical to the time frame).
If deriving the ending time frame from the "EventStart" date, "EventEnd" must be a numeric value AND include the
duration type using the "DurType" tag. The "DurType" tag supports three values "d" (days), "h" (hours), or "m" (minutes).
For example, if a seminar is 3 days long, you could either explicitly define the "EventEnd" date or derive the end date from the
"EventStart" date using:
Putting it all together, if a pagent was 90 min. long, the combination of tags could be something like:
<input type="hidden" Name="ID" Value="XMAS">
<input type="hidden" Name="Describe" Value="Christmas Pagent Tickets">
<input type="hidden" Name="EventStart" Value="12-24-2005 7:00 PM">
<input type="hidden" Name="EventEnd" Value="90">
<input type="hidden" Name="DurType" Value="m">
<input type="hidden" Name="Price" Value="8.00">
The "DurType" fields are not case-sensitive. For example, "H" and "h" are equivalent. In order for an item's
time frame to be tracked, the item must include both an "EventStart" date and "EventEnd" date or
an "EventStart" date, "EventEnd" numeric value and "DurType" indicator. See the Reservation and Appointment Event samples
in the Help Center.
The "EventStart", "EventEnd", and "DurType" tags can also be passed as modifiers.
Tip - Click here for advanced "EventStart", "EventEnd" modifier options.
The "OneTime" tag is used to add a one-time amount to an item. This
is similar to "Price" except that it is NOT multiplied by the quantity of items ordered. As such, it is not shown as
the calculated Unit Price in the cart, however it is added to the line item total for the item.
For example, suppose an item costs $8.00 each and there is a "one-time setup fee" of $5.00 for the item. You'd use the
"Price" tag to specify the $8.00 unit price and the "OneTime" tag to specify the $5.00 one time fee.
If a shopper ordered qty 1 of this item, the unit price would be $8.00 and the line item total would be $13.00 ($8.00 unit price X qty 1) + $5.00 one-time fee.
If a shopper ordered qty 5 of this item, the unit price would be $8.00 and the line item total would be $45.00 ($8.00 unit price X qty 5) + $5.00 one-time fee.
Use the "OneTimeLabel" tag to provide a descriptive name for the "OneTime" field. If not specified, the text "One Time:" will be displayed in the cart.
When a customer completes an order, you receive an e-mail notification at the e-mail address(es) specified in
your Profile Manager on the "E-mail" screen automatically. The shopper also receives an e-mail copy of the order automatically.
However, if you need to send an additional copy of the order based on a particular product, you can use the "AddEmail" tag.
Just define an additional e-mail address in the "AddEmail" tag and the address specified will also receive a copy of the
order notification. This can be useful if a particular department only needs to receive certain e-mails.
Use the "GiftCertificate" tag if you are selling a gift certificate product that your shoppers can redeem online.
When specified, the cart will generate a unique Gift Certificate for the amount defined by the "Price"
tag. The shopper will see the code only if payment of the order is authorized. The shopper can then redeem the Gift Certificate
through the cart at a later time by ordering other products and services from your site.
"GiftCertificate" supports two values - "Y" for yes or "N" for no. These
values are not case sensitive, so "Y" and "y" are equivalent, as are "N" and
"n".
When set to "Y", the cart will generate the code upon order finalization. You will see the code in Gift Certificates screen in your cart profile.
You can use the "GiftCertificateStart" and "GiftCertificateEnd" tags to
determine the time period in which the gift certificate can be redeemed and you can restrict the gift certificate to specific individuals via the
"GiftCertificateEmail" tag.
If set to "N" or blank, the item is treated like any other product.
See the "Gift Certificates" menu item and Help in the Profile Manager for additional information or check out the Gift Certificate code samples via the Help Center page.
The "GiftCertificateStart" and "GiftCertificateEnd" tags allow you to determine the time span within which a gift certificate can be redeemed.
These tags are only used if the "GiftCertificate" tag for a product is set to "Y".
"GiftCertificateStart" must be a date value using the format MM-DD-YYYY. If a "GiftCertificateStart" value is specified, the gift certificate can only be
redeem on the date specified or later. If no "GiftCertificateStart" is specified, the gift certificate can be redeemed immediately upon creation of the
gift certificate code (which only happens after payment for the order has been approved). Ex.
"GiftCertificateEnd" may be either a date value using the format MM-DD-YYYY or a positive numeric value indicating the number of months a gift certificate can be redeemed.
If a numeric number of months is defined, the "GiftCertificateEnd" is determined to be that many months after the "GiftCertificateStart" date. If no "GiftCertificateEnd"
tag is defined, there is no end period on using the gift certificate. Ex.
The "GiftCertificateEmail" allows the shopper to associate a specific Gift Certificate code to a specific e-mail address. This allows your customers
to give gift certificates for your products and services to their family and friends.
This tag is only used if the "GiftCertificate" tag for a product is set to "Y".
If passed, the "GiftCertificateEmail" value must be a valid e-mail address format. If no "GiftCertificateEmail" tag is passed, the cart will prompt the shopper to enter the e-mail address for the recipient of the Gift Certificate.
If no "GiftCertificateEmail" value is defined, the gift certificate is automatically associated with
the shopper placing the order and they can give the code to their family or friends themselves. The e-mail address specified by the "GiftCertificateEmail" field will receive an e-mail notice that they have received a gift certificate.
The "GiftCertificateMessage" allows the shopper to add an optional 200 character message with the Gift Certificate. The recipient of the Gift Certificate will see this
message in their e-mail notification.
This tag is only used if the "GiftCertificate" tag for a product is set to "Y".
A line-item is each product (or item) that shows up on separate "line" in the first cart screen. Normally, each line-item is identified by its own "ID" tag.
However, if you want to use the same "ID" with different options (such as different "Size" or "Color" options), you would set the "Multi" tag to "Y". This allows the same "ID" with different options to be shown in the cart as separate line-items.
The "DiscStr" tag allows you to define Qty discounts but this only applies to the individual line-item. To allow Qty discounts across multiple line-items, you can use the "GroupCode" tag to define a group of items. The GroupCode can be any alpha-numeric value (don't use spaces or non-ASCII characters). The GroupCode allows a single "ID" with multiple options or even different "ID" values to be grouped together for the purpose of group discounts. Use the "Group Discounts" screen in the Profile Manager to define the discount thresholds and values using the same code that you specify in your HTML using the "GroupCode" tag.
Note - You will likely only want to use either the "DiscStr" or the "GroupCode" however they can both be applied to a product. When both are defined, the "DiscStr" discount is applied first and then the "GroupCode" discount is applied.
Coupon discounts will be applied to products in the cart that have not been explicitly excluded from discounts by the "DiscItem" variable. If you want to limit one or more specific products to a specific coupon,
you can include a "LimitCode" variable set to the the value of the coupon code as part of the product's definition.
To create a coupon that is specific to one or more products, you would define the coupon normally using the "Coupons" screen in the Profile Manager. However, when defining the
coupon, set the coupon's "Exclusivity" field to the "Exclusive and limited by LimitCode" option. Then, within the <form></form> tags of those "Add to Cart" buttons
that are eligible for the coupon discount, include a "LimitCode" variable set to the same value as the coupon code.
For example, if you created a coupon called "NewSpecial" and set it's "Exclusivity" field is set to "Exclusive and limited by LimitCode", you would include the following variable
in the product(s) that are eligible for the "NewSpecial" discount:
If a buyer uses the "NewSpecial" coupon, the coupon's discount will be applied only to those product's that contain a "LimitCode" variable set to "NewSpecial".
No discount will be applied to any other products in their cart that do not have a "LimitCode" variable that matches the coupon code.
Tip: because the "LimitCode" restricts a specific product to a specific coupon code, you could also use the "LimitCode" variable to exclude specific products from other coupons.
When you have non-limited coupons defined, product's containing a "LimitCode" will not be discounted when the buyer uses any coupon codes which do not match the "LimitCode".
The effect is similar to setting the "DiscItem" variable to "N" except the coupon defined by the "LimitCode" will still be permitted.
Note:
ASecureCart supports exclusive and non-exclusive coupons but the "LimitCode" variable only works with exclusive coupons. It cannot be used with non-exclusive coupons
and only one limited coupon code can be redeemed per order. If you define multiple "LimitCode" coupons and a buyer tries to redeem multiple, coupon-specific products,
the discount will only be applied to the first coupon entered. See the description of the "Exclusivity" field on the "Coupons" screen in your ASecureCart account for additional information.
When a customer completes an order, both you and the shopper receive a detailed e-mail notification automatically. You can also specify
that your shipping department, drop shipping company, or other party receives an e-mail notice by using the "DropShipEmail" parameter. The
e-mail message that is sent to the e-mail address(es) specified in the "DropShipEmail" field will not contain the item pricing, only
the items ordered, delivery information and shipping method. This allows you to keep your prices private from your external shipping partners.
Also, the e-mail received by your shipping partner will only include items that they are responsible for. If you have multiple drop ship partners who
each handle different product lines, use the "DropShipEmail" field to associate a particular product to a particular shipping partner. For example, if
"JB's Shipping" is responsible for your "Widget" product and "ACME Shipping" handles the "Flipitz" product, enter JB's e-mail address in a "DropShipEmail" field
for the "Widget" product and enter ACME's e-mail address in the "DropShipEmail" field for "Flipitz" product.
If a shopper orders a "Widget", only JB's Shipping would get the shipping e-mail. If a shopper orders a "Flipitz", only ACME Shipping gets the shipping e-mail. However,
if a shopper orders both the "Widget" and the "Flipitz", both shippers get an e-mail but JB's Shipping only shows the Widget and the e-mail to ACME Shipping only shows the "Flipitz".
Note - the e-mail address defined in the Profile Manager always receives the normal order notification e-mail, regardless whether there is
an "DropShipEmail" value specified. In addition to the normal order notification, you also receive a copies of each shipping e-mail sent to
your shipping partners. This way, you get copies of the exact same e-mail notices that your shipping partners receive.
Recurring billing is the ability to charge the shopper on a regular schedule, such as subscriptions.
This ability is a function of a payment gateway more than the cart. However, ASecureCart can pass the appropriate information
to those payment gateways that support recurring charges/subscriptions, such as Authorize.Net, PayPal Website Payments Pro, SecurePay, Beanstream, LinkPoint API, etc.
Often times, the recurring billing option is an add-on service to your normal gateway service and there may be additional charges for the service.
You will need to contact your payment gateway to determine if your gateway supports recurring billing and what additional costs, if any, are associated with it.
Some payment gateways (like Beanstream and PayPal Website Payments Pro) allow the cart to pass enough information to create the recurring transaction profile for the shopper.
When the transaction is completed successfully, the shopper's credit card will be charged initially and the recurring billing will automatically occur at the billing frequency that
you decide.
Other payment gateways (like Authorize.Net, LinkPoint API, and SecurePay) allow the cart to pass in parameters to indicate the transaction can be converted to recurring.
In these cases, the cart will flag the transaction as "to be recurring" but an additional step is required inside your payment gateway profile to activate the recurring billing.
In either case, the cart's "Recur" variable will be the same. The value of the "Recur" variable must consist of two characters - the "period" and the "increment". The "period" portion of the
value is either "M", "D", "W", "Q", or "Y" and they indicate:
M = Month
D = Day
W = Week
Q = Quarter
Y = Year
The "increment" portion should be a numeric value which reference the number of "periods" that will make up the billing cycle. For example, "M1" would be once a month, "D9" would be every nine days,
"W2" would be every two weeks, etc.
Examples:
Once every month:
<input type="hidden" Name="Recur" Value="M1">
Once every day:
<input type="hidden" Name="Recur" Value="D1">
Once every 2 weeks:
<input type="hidden" Name="Recur" Value="W2">
The "Recur" tag also supports the ^pricemodifier so you can specify different prices based on different billing periods,
such as:
<select name="Recur">
<option value="D1^5.00">Daily - $5.00
<option value="W1^25.00">Weekly - $25.00
<option value="M1^75.00">Monthly - $75.00
</select>
Note - ^price modifiers must be numeric values.
Note - For backwards compatibility with earlier systems, if the "increment" portion is not provided, the cart will automatically assume an increment of "1".
Note - Some payment gateways also support the number of cycles. A second ^ can be used to specify the number of cycles.
For example, the following would indicate a monthly charge for 12 additional periods (in addition to the initial charge at the time the order is submitted, resulting in a total of 13 payments):
<input type="hidden" name="Recur" value="M1^^12">
ASecureCart is integrated with TaxCloud, an easy-to-use, sales tax management service for U.S. retailers, to handle all aspects of sales tax, from collection to filing -- and it's completely free.
TaxCloud uses Tax Identification Code (TIC) values for each product or service
sold to accurately apply sales and use tax rates and exemptions.
The "TaxCloud Destination Based Tax Calculations" link on the "Taxes" screen (US merchants only) within your ASecureCart account can be used to configure
your TaxCloud settings, including default TIC codes. More information on TaxCloud can also be found here or on their FAQ.
The default TIC values set at the cart account level are useful if you primarily sell one classification of goods or services.
You can use this "TIC" variable to override the default TIC settings and assign an individual TIC value for a specific product or service.
In other words, when a product contains a "TIC" variable, the product's individual "TIC" value will supersede the default TIC values defined on the TaxCloud configuration screen in your ASecureCart account,
while any products that do not contain a "TIC" variable will use the default TIC values defined in your ASecureCart account (assuming you have TaxCloud enabled in your ASecureCart account).
The TIC values are numeric codes. For detailed information on the individual TIC values, click here.
For example, if you were selling Bike Helmets, the TIC variable would look like this:
<input type="hidden" Name="TIC" Value="92007" />
Tip - When using the "TIC" variable to assign a specific TIC for a product, be sure the value you assign is valid to ensure proper tax calculation.
Additional Modifiers -
The Size, Color, AddOn, and NAddOn tags support additional modifiers that can
be used to set the Price, Ship, Weight, QtyMultiples, QtyMin, QtyMax, or SKU
values using the format value^Price^Ship^Weight^QtyMultiples^QtyMin^QtyMax^SKU^EventStart^EventEnd^DurType^OneTime.
For example, an AddOn checkbox that marks the price up by $2.00 and must be
ordered in multiples of 12 with a minimum quantity of 24 would be:
<input type="checkbox"
Name="AddOn1" Value="Extra Thing^2.00^^^12^24">
Tip - The Price portion can either be an absolute amount such as "5.00" or a percentage
amount such as "15%". When a percent amount is used, the percentage value is the
base price of the item, as determined by the original "Price" options. Further, the
percentage can also be a discount by specifying a negative percent, such as "-10%"
Since the embedded values are positional, placeholders must be included for
non-used positions if a subsequent modifier is used. For example, the below
AddOn requires that item "Model A" have a minimum order of 2 but no Price,
Ship, Weight nor multiple modifiers. Model B is an extra $2, has a minimum
order of 10 and must be ordered in multiples of 5 while Model C is an extra $3,
has a minimum order of 16 and must be ordered in multiples of 8. Since none of
the options have a maximum limitation, no placeholder is required for the last
modifier.
<select name="AddOn1">
<option value="Model A^^^^^2">Model A
<option value="Model B^2.00^^^5^10">Model B - Add $2.00
<option value="Model C^3.00^^^8^16">Model C - Add $3.00
</select>
Since non-used positional placeholders are not required for non-used trailing
modifiers, these are all valid settings:
Price only (adds $2.00 to the price for each item ordered)
<OPTION value="Some
Item^2.00">Some Item
Price only using a percentage (adds 15% to the price for each item ordered)
<OPTION value="Some
Item^15%">Some Item
Weight only
<OPTION value="Some
Item^^^4">Some Item
Ship only
<OPTION value="Some
Item^^2.25">Some Item
Price and QtyMin
<OPTION value="Some
Item^2.00^^^^10">Some Item
Price and QtyMultiples
<OPTION value="Some
Item^2.00^^^10">Some Item
QtyMin only
<OPTION value="Some
Item^^^^^10">Some Item
QtyMultiples only
<OPTION value="Some
Item^^^^10">Some Item
SKU Append Example: Append an AddOn and Color to a base SKU value resulting in
a SKU of "XYZ-4-G"
<input type="hidden"
name="SKU" value="XYZ">
<input type="hidden" name="SKU_Rule" value="accumulate,AddOn,Color">
<input type="hidden" name="Color" value="Green^^^^^^^-G"> <OPTION
value="Some Item^^^^^^^-4">Some Item
SKU Overwrite Example: Keep overwriting the SKU, first with an AddOn value,
then a Color value resulting in a SKU of "ABC-GRN"
<input type="hidden"
name="SKU" value="ABC-0">
<input type="hidden" name="SKU_Rule" value="overwrite,AddOn,Color">
<input type="hidden" name="Color" value="Green^^^^^^^ABC-GRN"> <OPTION
value="Some Item^^^^^^^ABC-4">Some Item
EventStart and EventEnd dates
<OPTION value="7 Day Cruise^^^^^^^^3-21-2005^3-28-2005">7 Day Cruise March 21st thru March 28th, 2005
EventStart and derived EventEnd
<OPTION value="7 Day Cruise^^^^^^^^3-21-2005^7^d">7 Day Cruise - March 21st thru March 28th, 2005
OneTime fee - an $8.00 item with a $5.00 one time fee
<OPTION value="Custom T-Shirt^8.00^^^^^^^^^^5.00">Custom T-shirt: $8.00 ea. (plus one time $5.00 setup fee)
Tip - If a form contains both a discrete QtyMultiples, QtyMin, and QtyMax values
and embedded modifiers, the embedded values will supercede the discrete values.
Embedded Price, Ship, and Weight values are added to any discrete values.
Tip - If a form contains a discrete SKU value and embedded modifiers, the
embedded values either overwrite or be appended to the discrete SKU value based
on the "sku_rule" used. If a "sku_rule" is not defined in the Profile Manager
and no "sku_rule" value is passed into the page, the ASecureCart engine will not
know how to use the modifiers. In this case, modifiers will be ignored and only
the discrete value will be used.
