|
|
Setting Up Your Shopping Cart Software - Add-to-Cart Code Explanations
All the information that you will need to setup your shopping cart software is listed here with the appropriate explanations for each step. Setting up online shopping carts can be difficult, here we make it easy for you
- DesignCart 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.
- 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.
<form method=POST action="https://www.designcart.net/cgi-bin/cart.cgi">
<input type=hidden name=additem value="cartid|itemname|itemcost|itemquantity
|itemno|itemhandling|itemshipmethod|itemweight|itemexempt|itemdiscount
|itemsilentpost|itemdropshipzip|itemESD|itemRecurring">
<input type=submit value="Add To Cart">
</form> |
- Field 1: cartid (required) -- Usernames (cart ID's) are assigned to you upon sign-up. This username identifies you to the DesignCart 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>
| This feature may be combined with either previous option.
Cost Multiple product listing AppendItem
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>
| Quantity Multiple Input VARquantity
--AND--
Paste this before the </form> tag . . .
<input type=text name="VARquantity" size=2 value=1>
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 DesignCart. 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
| 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. |
- 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.
DesignCart 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
Customer
Service.
|
|
