Add To Cart Codes Explanation

CartManager uses several set fields in the "Add To Cart" action. Each of the variables are separated by a | character (pronounced "or" and is found on the keyboard above the back-slash key) and allows information to be compiled into a single variable, reducing data entry time.
The field separators (the first 4 are required) must be used in proper order. If a certain field is not applicable to you, leave it empty as a placeholder to prevent the field count from being thrown.

If your product entry requires a quotemark you must use the code " or data will be lost.

Field order.
Click for more infomration.

1.: cartid
2.: itemname
3.: itemcost
4.: itemquantity
5.: itemno
6.: itemhandling
7.: itemshipmethod
8.: itemweight
9.: itemexempt
10.: itemdiscount
11.: itemsilentpost
12.: itemdropshipzip
13.: itemESD
14.: itemRecurring
15.: itemThumbnail
16-19.: Reserved for future use
20-29.: Misc Product Information

Here is an example of the HTML needed to create an add button. Please remember that you would need to modify each field. If you are not going to use some of the fields, simply leave them empty.

Field 1: cartid (required) -- Usernames (cart ID's) are assigned to you upon sign-up. This username identifies you to the CartManager system and is used for your cart configuration.

Only alpha-numeric characters are permitted and it is important to remember that usernames are case sensitive.

SAMPLE CARTID USERNAMES
laneyent
Cart4You
443john
Field 2: itemname (required) -- The product description. A short text description should be used to remind the customer what the item is when they review their cart contents. A larger description should be placed on your Web Page.

Remember, if you need to use reserved characters (e.g. quotation marks) use " etc.

SAMPLE DESCRIPTIONS CODES WHAT YOUR CUSTOMER WILL SEE
Teal Scarf
"M" Hat
Things & Stuff Teal Scarf
"M" Hat
Things & Stuff

Field 3: itemcost (required) -- The price of the product. All entries MUST be numeric.

The field is also expandable and may contain entries for additional costs and/or used to include the cost of accessory items. This is accomplished by referencing "VARcost" or "AppendItem" and inserting additional code as shown.

UNIT COST	VARIABLE CODE
Cost Single Selection	$xxx.xx
Cost Multiple Selection VARcost Paste this before the </form> tag . . . `<select name="VARcost"> <option value="$x">$x</option> <option value="$y">$y</option> <option value="$z">$z</option> </select>` To create this sample product listing. . .
This feature may be combined with either previous option. Cost Multiple product listing AppendItem To create a sample product listing. . . YES/NO Include Pull-Handle -- $9.00 Include Brass Wheels -- $14.00 Add Leather ID Tag -- $6.00 Go to Example 8 for a complete example including source code.

Field 4: itemquantity (required) -- This variable contains the default number of items a customer may purchase at one time. The entry generally is 1 (one) but could be any number (i.e. a hand-knit sock is sold in sets of 2). You should indicate these quantities in your Web Page description to assist the customer when ordering.

The field is also expandable and may contain entries to either select from a predefined list of values or input the exact number of items desired. This is accomplished by referencing "VARquanitity" in the field and inserting additional lines before the </form> closing tag.

QUANTITY	VARIABLE CODE
Quantity Single Selection (customer has no choice, x items automatically placed in shopping cart)	x
Quantity Multiple Selection VARquantity --AND-- Paste this before the </form> tag . . . `<select name="VARquantity"> <option value="A">A items</option> <option value="B">B items</option> <option value="C">C items</option> </select>` To create this sample product listing. . .
Quantity Multiple Input VARquantity --AND-- Paste this before the </form> tag . . . `<input type=text name="VARquantity" size=2 value=1>` Enter # of items To create this sample product listing. . . Enter # of items

Field 5: itemno (recommended) -- The part number of your product or service.

Even if you do not use part numbers, it is recommended that you assign a part number code for each item you are selling. They are very useful if you ever decide to use the cart features "Coupons" or "Inventory Control".

SAMPLE ITEMNO CODES
XR4501
XR-4501
XR4_501

Field 6: itemhandling (optional) -- The price to ship and/or process (handle) the product. This amount can be applied in addition to the rate calculated using the Approved Shipping Methods or Shipping By Table used within CartManager. The variable allows you to adjust your fees on a per product basis and possibly create a higher profit margin on items that may be popular, cheaper/more expensive, or easier to deliver. All entries MUST include a currency symbol ( $ ) or a percent symbol ( % ).

This variable is expandable and can accommodate a custom handling scale. To build your price structure, simply start with the first value, insert a colon, and indicate its price. Add additional quantities and their prices separated by another colon until all desired fees are inserted.

ITEMHANDLING CODE	Description
$x	Each item adds $x to handling.
x%	Each item adds x% of the items price to handling.
1:$x:10:$y:20:$z	Quantities of 9 or less charge $x each. Quantities of 10-19 or less charge $y each. Quantities of 20 or more charge $z each.
>1:$x:2:0	Only charge $x for shipping, no matter how many they purchase
#12:$x	Charge $x for every dozen purchased

Note: If the "PerHandling" option is used in Field 9: itemexempt (optional) then the amount will not be calculated per product, but only once per order.

The "PerHandling" option is only intended to be used with the "$x", and "x%" Item Handling codes. To use it with the other, more complex codes may result in an error.

Shipping/Handling charges may still come from other sources such as UPS or FedEx. Or from other products having their own handling fee.

Field 7: itemshipmethod (optional) -- You may designate a preferred shipping method for each product. During the checkout procedure, the shopping cart program will automatically calculate the exact price to ship the product via the indicated method, this is in addition to any charges created by itemhandling. Please insert the code into this field exactly as it appears below.

The field is also expandable and may contain selectable entries. This is accomplished by referencing "VARshipping" in the field and inserting additional lines before the </form> closing tag.

Note: "Prompt" allows your customers to choose a shipping method from your Approved Shipping Methods list using a drop-down menu on the top of the "Shipping/Billing" page.

Shipping Single Selection

Insert one of these options into the field . . .

Prompt
Price
Price2
Price3
Price21
Weight
Weight2
Weight3
Weight12
Quantity
Quantity42
Free Shipping
Customer Pickup
Free Shipping Domestic Only
Standard Delivery
USPS Priority Mail
USPS Express Mail
USPS Parcel Post
UPS Ground
UPS Next Day Air
UPS 2nd Day Air
UPS 3 Day Select
UPS Standard
UPS Worldwide Express
UPS Worldwide Expedited
UPS Freight LTL
FedEx Ground
FedEx Priority Overnight
FedEx Standard Overnight
FedEx First Overnight
FedEx 2 Day
FedEx Express Saver
FedEx International Priority
FedEx International Economy
ZONES
*Note: This is not a complete list of all available shipping methods. For a complete list please login to your shopping cart and click on the "Add To Cart" button builder

Shipping Multiple Selection VARshipping
--AND--
Paste this before the </form> tag . . .

<select name="VARshipping">
<option value="A"> Method A</option>


<option value="B"> Method B</option>
<option value="C"> Method C</option>
</select>

Field 8: itemweight (optional, may be required by itemshipmethod) -- This field contains the item weight. In order to use approved shipping standards, all products using itemshipmethod must have their weight listed in pounds.

Weight conversion table
Ounces Pounds
1 = 0.0625
2 = 0.1250
3 = 0.1875
4 = 0.2500
5 = 0.3125
6 = 0.3750
7 = 0.4375
8 = 0.5000
9 = 0.5625
10 = 0.6250
11 = 0.6875
12 = 0.7500
13 = 0.8125
14 = 0.8750
15 = 0.9375
16 = 1.0000

Most merchants will only need to enter weights here. However, some may need to add box dimensions. This can be done using this format:

QTY#WEIGHT:LENGTH:WIDTH:HEIGHT

For example if you have a 6 pound box that measures 10 inches by 8 inches by 4 inches you would enter:

6:10:8:4

You can specify multiple boxes in an item like so:

WEIGHT:LENGTH:WIDTH:HEIGHT=WEIGHT:LENGTH:WIDTH:HEIGHT=WEIGHT:LENGTH:WIDTH:HEIGHT

So if you have the original box above as well as a 3 pound box measuring 5 inches by 3 inches by 1 inch you enter

6:10:8:4=3:5:3:1

Note: If you do not specify a length, width, and height then the shopping cart will use an internal algorithm to guess the dimensions. If you require extremely accurate shipping charges then you MUST enter box dimensions.

Field 9: itemexempt (optional) -- This entry allows an item to be sales tax-exempt, shipping exempt, or quantity exempt, etc.

If the product is not to be taxed, simply include the code "Tax" meaning tax exempt. The same may be done with "Shipping", etc.

If you need to enable more then one of the exempt options simply separate them by a colon.
Shipping:Tax:GiftCertificate

See a list of available options in the table below.

TYPE OF EXEMPTION	EXEMPT CODE
Tax Exempt	Tax
Change the tax rate from your default settings for this product. This will allow you to have a different tax rate than listed in your Current Tax Rates. Example: ChangeRate(Utah)=0.0625 ChangeRate(ALLRATES)=0.03	ChangeRate(XX)=Y.YY
Shipping Exempt	Shipping
Use this if you have a product that cannot be sold in certain locations. Examples: NotAllowedShipping(US:UT) NotAllowedShipping(US:CA) NotAllowedBilling(US:CA)	NotAllowedShipping(XX:XX)
Creates a special product. This product will automatically create a gift certificate for later use within the cart. Gift certificates should also be labeled TAX and SHIPPING exempt. (eg. TAX:SHIPPING:GIFTCERTIFICATE)	GiftCertificate
Quantity cannot be modified in any way.	Quantity
The quantity cannot be set higher than X.	Max=X
The quantity cannot be set lower than X.	Min=X
Changes how handling is charged. It will now only charge the handling fee once, and NOT per item.	PerHandling
Tax and Shipping exempt.	Tax:Shipping
If a shopper has a valid Tax ID, and you still need to charge that person tax for this item, enter this into your add button code.	NoTaxID
If you have set XXX Products To Be Purchased On Backorder to "Allow" or "Automatically Add" then you can use this phrase to turn off the backorder ability for a product.	Backorder
Allows your to setup a Vendor code so that you can print your packing slips out for each individual vendor. X is simply a number from 1-255.	Vendor=X
Allows you to specify an alternate Company Logo image to be displayed in the shopping cart. The image must exist in the Upload Custom Images tool.	CompanyLogo=Image.gif
Allows BuyDRM as your ESD DRM provider. BuyDRM must have the product part number on file so the cart can retrieve a "coupon" from BuyDRM.	BuyDRM
Allows you to process your eBay auction payments automatically. AID is your eBay auction ID. TID is your eBay transaction ID.	eBay=AID=TID
The ability to group items together so that their quantity is adjusted at the same time. In this example all products with the matching "abc" tag will be grouped together so that their quantities match.	groupquantity=abc

Field 10: itemdiscount (optional) -- This variable allows either a dollar-discount or a percentage-discount. If you desire the product to offer a dollar reduction, simply include the code: $x dollar discount for product. If you want to give a savings percentage for the product, use the code: x% percentage of discount for product. All entries MUST be numeric and may include the currency ( $ ) or percentage ( % ) symbols.

Discounts are expandable by using the ( @ ), ( # ), or ( > ) symbols. To build a discount structure based on a price or quantity range use the ( @ ) or ( > ) symbols your range, a colon, then the discount amount. To give a discount on every Nth item use the ( # ) symbol the Nth item, a colon, followed by the discount amount.

Discounts that begin with #, @, or > can be made global. To do this simply end the discount code with the global identifier. If a product is not made global than the discount can only apply to the 1 specific cart entry.

DISCOUNT CODE	Description
$4.95	Each item is reduced in price by $4.95 Note: For discounts less than $1.00, include the 0 (zero) before the decimal point (e.g. $0.10).
#2:100%	Buy one get one free
50%	Wow this item is 50% off
>10:5%:20:10%:50:15%	Quantities 1-9 regular price Quantities 10-19 are 5% off Quantities 20-49 are 10% off Quantities 50+ are 15% off Note: For example if they purchase 20 products that are normally $100 each, the total price for all 20 would come out to $1930.00. Notice that the first 9 products are regular price, then 10-19 are 5% off, and finally the 20th is 10% off.
@10:5%:20:10%:50:15%	Quantities 1-9 regular price Quantities 10-19 are 5% off Quantities 20-49 are 10% off Quantities 50+ are 15% off Note: For example if they purchase 20 products that are normally $100 each, the total price for all 20 would come out to $1800.00. Notice that all 20 products got the 10% discount.
@$1000:5%:$2000:10%	Dollar amounts 0-999 are regular price Dollar amounts 1000-1999 are 5% off Dollar amounts 2000+ are 10% off Note: For an order amount of $999 or below there is no discount. For order amounts from $1000 to $1999 customers receive a 5% discount. Orders $2000 and above receive 10% off.
>$100:$10:global	Give an instant $10 rebate if $100 or more is purchased (one time only)
>1:$10:2:$0:global	Give an instant $10 rebate if 1 or more products are purchased (one time only)
#$100:$10	Give an instant $10 rebate for every $100 purchased
#2:100%	Buy one get one free
#3:50%	Buy two get the third one at half price
#3:50%:half_off	This is a global discount. All items with this discount code will be used for calculating the quantities
@10:5%:shirts	You could create a discount like this to allow customers to get a discount if they buy 10 or more or any shirt with this code

Field 11: itemsilentpost (optional) -- Occasionally you may need extra processing done on your website when a product is purchased. To accommodate you the cart has the ability to send data back to the URL you specify in the "ItemSilentPost" field. The cart will do a silent post to the URL using the POST method once the product has been purchased.

If you choose, you can setup verification of the silent post, simply enter the ItemSilentPost Verification Text into step #8 Advanced Settings. The cart will verify that this text exists in the data that your URL returns. If it does not, we will send you email notification that it failed to verify.

Note: ItemSilentPost can only to connect to destination port 80 or port 443. Please make sure your developers use these ports for communication. All connections will come from 192.41.22.30, please adjust your firewalls accordingly.

Here is the extra information that will be sent with each post.
ItemNo	the part number of the product
ItemQuantity	how many were purchased
UnitPrice	The unit price of the product purchased
OrderNumber	which order this post is for
OrderShipping	the total shipping charges for the order
OrderTax	the total tax amount for the order
OrderGiftCertificates	how much of the order, if any, was paid for by gift certificates.
OrderCoupons	A comma delimited list of coupons and how much the coupon was valid for. e.x. coupA,4.95,coupB,12.81
OrderCOD	the additional COD charge applied to this order, if any.
OrderRushOrder	the rush order charge for this order, if any.
OrderTotal	The grand total for this order.
Name	the customers name
EMail	the customers email address
Phone	the customers day phone number
PayMethod	What method of payment did the customer use (VISA, AMEX, etc...)
CustomerID	This is your customer ID that can be sent to us using a CustomerID hidden tag in any cart button.
GatewayID	If the order was processed through a payment gateway then this is the transaction number for your payment gateway.
OrderStatus	This the current Order Status.
ShipMethod	The shipping method that was selected for this item
ShipName	This is your customers shipping name
ShipAddr1	This is your customers shipping street address line 1
ShipAddr2	This is your customers shipping street address line 2
ShipCity	This is your customers shipping city
ShipState	This is your customers shipping state
ShipZip	This is your customers shipping zip code
ShipCountry	This is your customers shipping country code

Please note that this is done for each individual product purchased, so it may cause extra delay in the display of the customer's final receipt if they purchase many different items.

Note: You must enter a fully qualified URL for this to properly connect (eg http://www.your_site.com/thescript.php)

PHP Example for maximum security

This first script would be run from command line to generate the URL string that you place into the shopping cart itemsilentpost field.

<?

# constants

define( 'SERVERSECRET', 'shh do not tell' );

define( 'ITEMSILENTPOSTVERIFICATION', 'must match ItemSilentPost Verification Text in step 8' );



# create the URL - put this $url in your add button

$hash = sha1 ($product['ItemNo'] . SERVERSECRET . ITEMSILENTPOSTVERIFICATION);

$url = 'http://www.your_site.com/example/script.php?hash=' . rawurlencode($hash);

print "$url\n";

?>

This second script would be installed on your server as a web page at the $url shown in the first script.

<?

# constants, the secret must match what is in the first script

define( 'SERVERSECRET', 'ssh do not tell' );



# verify the URL that came from the cart

$hashCmp = sha1 ($_POST['ItemNo'] . SERVERSECRET . $_POST['ItemSilentPostVerification']);

if ($hashCmp == $_POST['hash']) {

  print "Content-Type:text/plain\n\nhash verified - ".$_POST['ItemSilentPostVerification']."\n";

  # do important stuff here

  # do important stuff here

  # do important stuff here

} else {

  print "Could not verify hash";

}

?>

Field 12: itemdropshipzip (optional) -- This variable allows the merchant to ship the products from any warehouse(s) other than the one listed in your main Drop Ship Information.

Please enter the postal code, and the 2 digit state code of this product's warehouse here.

Examples:
84604:UT
or
84604:UT:US

Note the full "84604:UT:US" format is highly recommended as the other more brief formats may cause shipping errors if your business is not located in the same state as the drop ship zip code.
Field 13: itemESD (optional) -- This variable allows the merchant to create products that are shipped electronically. Instead of shipping a package to the customer, the customer will be able to download your file(s) immediately upon purchase.

Valid values can be:
- yourfile.exe - the file name in our ESD system. Uploaded files are only available to the customer that purchased them.
- http://www.yourserver.com/somewhere/yourfile.exe - URL of the file your customer will be allowed to download upon purchase. URLs entered in this manner are not protected, it is the merchants responsibility to ensure that the download is allowed only to paying customers.
- yourfile1.exe yourfile2.exe - Simply separate multiple files/URLs by a space.
If you are using a file name then the file must be uploaded to your cart admin area (see Upload ESD File).

An email address may be sent (eg FILENAME=EMAIL) to the cart, this will cause the cart to not allow the purchaser to download the product. But, rather it will send an email to the specified address with a link to download. You can use this to allow your customers to send an ESD file as a gift to another person.

Note: ESD files uploaded to us are only available for download for 3 days after the first attempt to download the file. After this time, the customer will need to contact the place of purchase for any assistance in getting the file.

Note: Use the email system with care. Many mail servers will refuse delivery if the file is to large. For example, many will reject files larger then one megabyte.

Field 14: itemRecurring (optional) -- This variable allows the merchant to create products that have an ongoing charge. Possible options for the frequency are Weekly, Bi-Weekly, Semi-Monthly, Monthly, Quarterly, Semi-Yearly, Yearly, or X-Daily (where X is any number of days)

How to build a recurring code

1	2	3	4	5	6	7
Optional	Required	Required	Optional	Successes Required For Cancellation Optional	Failure Type Optional	Recurring Type Optional
`7-Daily:`	`Monthly`	`=-1`	`=$4.95`	`=Cancel(2)`	`=Single`	`=Product`
`7-Daily:Monthly=-1=$4.95=Cancel(2)=Single=Product`

Part 1)	Optional. If omitted then part 2 will be used by default. This field indicates when the first re-occurrence of the charge will happen.
Part 2)	Required. The product will recharge your shopper at this frequency.
Part 3)	Required. The product will recharge your customer this many times before being removed from the system. Setting this to -1 will charge the customer permanently until canceled.
Part 4)	Optional. If left blank the original product price will be used. Enter the amount to charge your customer.
Part 5)	Optional. If left blank they can cancel at any time. Enter =Cancel(5) if you require 5 Successful Transactions before allowing the shopper to cancel.
Part 6)	Optional. If left blank multiple failures will be recorded.
Part 7)	Optional. If left blank only part 4 will be charged. Enter =Product to include shipping and tax charges.

More Examples	Description
`Monthly=4`	Charge the product price for 4 additional months.
`Yearly=1`	Charge the product price for 1 additional year.
`Monthly=-1`	Charge the product price FOREVER until removed. Please note that some merchant account agreements may prohibit recurring charges that do not have a defined termination date.
`Monthly=-1=4.95`	Same as above, except that it will charge 4.95 for the additional months rather than the original listed price.
`42-Daily=-1`	Repeat the billing cycle every 42 days.
`30-Daily=-1=Cancel(2)=Single=Product`	Shipping a new product every 30 days. Only 1 failure is recorded... when they fix their billing the product will ship and the Next Billing Date will reset.

Field 15: itemThumbnail (optional) -- Upload your graphic using the Upload Custom Images. Once you have successfully uploaded your image simply enter the name of the image here. This will instruct the shopping cart to display that image next to the product description.

Note: While a thumbnail can be of any size, we recommend you use images 300x300 or smaller.
Fields 16-19: reserved for future use -- While these fields are not currently used by the shopping cart. We may use them in the future.

We recommend you avoid placing any data in these fields as it may cause problems as we make future updates to the shopping cart.
Fields 20-29: Misc Product Information (optional) -- These fields are reserved for merchant use. The shopping cart will not use these fields other then to store them for the merchant to retrieve later.

When a customer selects an option from special product properties, the selection is saved in one of these fields. Merchants can have up to 10 special product properties to be recorded; any properties after 10 will be omitted.

The questions could be anything. Here are some examples:
Please enter your mothers maiden name: Smith
What is your favorite color: Blue
Gender: Male/Female

The answers are limited to 255 characters, anything after that will be lost.

CartManager does not use the answers, it only display them here:
1) The receipt
2) In a CSV file they can download

A merchant can download the CSV file here
1) Login
2) Order History
3) Download My Orders
4) You can then open the downloaded file
5) Open the file in Excel or any other program that can open a CSV file

The file format can be found here CSV Format Details

If you need additional assistance please contact CartManager Customer Service.