Add To Cart Form (tag pair)

This tag allows you to add a products to your shopping cart. A video tutorial on this tag is available..

See also:

  • item_options Outputs available item options. This is referenced in the [examples][].

Table of Contents

Parameters

In addition to the parameters listed here, you may also use any of the Global Form Parameters.

entry_id

The entry_id of the product. In this example we are using a segment variable to set the entry_id.

entry_id="{segment_3}"
quantity

The quantity to add to the cart.

quantity="1"
on_the_fly

This allows you to add an on-the-fly product (a product with no entry) to your cart.

on_the_fly="y"
title

Set the title of an on-the-fly product.

title="Red T-Shirt"
price

Set the price of a product. This will override the price you have setup and mapped in your products channel/channel.

price="9.95"
shipping

Set the shipping cost of a product. This will override the shipping cost you have setup and mapped in your products channel/channel.

shipping="4.95"
weight

Set the weight (for shipping calculations) of a product. This will override the weight you have setup and mapped in your products channel/channel.

weight="20"
allow_user_price

This allows your user (or you, with a hidden field) to set a price. This is useful for items like donations. You'll have to create a form field to add the price.

<input type="text" maxlength="7" size="5" name="price">

allow_user_price="yes"
allow_user_shipping

This allows your user (or you, with a hidden field) to set the shipping cost of a product. You'll have to create a form field to add the shipping cost.

<input type="hidden" name="shipping" value="{shipping_cost_field}" />

allow_user_shipping="yes"
allow_user_weight

This allows your user (or you, with a hidden field) to set the weight of a product. You'll have to create a form field to add the weight.

<input type="hidden" name="weight" value="{weight_field}" />

allow_user_weight="yes"
tax_exempt

By default all items are taxed. If you have an item that can't be taxed (like a donation) you must set the "tax_exempt" parameter to true/yes/1.

tax_exempt="yes"
shipping_exempt

By default all items are run through shipping calculations. If you have an item that isn't shippable (like a donation or download) you must set the "shipping_exempt" parameter to true/yes/1.

shipping_exempt="yes"
license_number

If this parameter is added, a license number will be generated on checkout and added to a license_number field (if you have one mapped) in your Orders and/or Purchased Items channels.

license_number="yes"
expiration_date

If you are saving your purchased items as entries, you may use this parameter to set the expiration date of the entry for this item. This parameter takes a number of DAYS from today's date to set the expiration date.

expiration_date="365"
upload_directory

If you plan to use the userfile input (documented below) you can optionally specify an upload destination. You can specify an EE directory ID, or a server upload path if you're feeling adventurous. If no upload directory is specified, cartthrob will use the first upload directory it can find. CartThrob will add the upload file name, and directory as item options (upload & upload_directory respectively). This value is ignored if no userfile input field is used to upload a file. If you plan to upload files with your add to cart action, make sure you specify the enctype parameter as well. 

upload_directory="1"
enctype

This allows you to set the enctype of the add to cart form. This is only useful if you add a userfile input and intend to allow the customer to upload files with the add to cart operation. 

enctype='multipart/form-data'

Variables

In addition to the variables listed here, you may also use any of the Global Tag Variables.

inventory:reduce

PLEASE NOTE: This tag is only needed in special circumstances Normally CartThrob will handle inventory reduction automatically. When one item, or a quantity of an item is added to the cart, CartThrob will check inventory at that time, and again at checkout. The only use of this tag, is if you want to also manipulate the inventory of another item for some reason at the same time, even though it isn't being added to the cart. This would be useful, for instance if you were giving away an item for free with each purchase and wanted to track that items inventory so you knew when to end the promotion.

This tag will give CartThrob instructions to reduce the inventory of the item specified, by the quantity specified. In this example, when the user checks out, the product with the entry_id of 6 will have it's inventory count reduced by 4. You can use this tag more than once.

{inventory:reduce entry_id="6" quantity="4"}

Form Fields

entry_id

The entry_id of the product.

<input type="hidden" name="entry_id" value="1234" />

title

Set the title of an on-the-fly product.

<input type="text" name="title" value="My Custom Product" />

language

There are several validation messages you may encounter with CartThrob's inventory system. These errors announce whether an item is out of stock. If you have a language you'd like these error messages to display in, you can add the 2 character ISO 639-1 language code (en), or the full language name (english). Language files control the contents of these validation messages.

<input type="text" name="language" value="en" />

quantity

The quantity to add to the cart.

<input type="text" name="quantity" value="1" />

userfile

You can upload files when you add an item to the cart, however, you must follow a few simple rules.

  • You can only upload one file per add-to-cart operation (due to a limitation of ExpressionEngine's built in file upload handling).
  • Your upload field must always be named userfile
  • You must add enctype=multipart/form-data parameter to the add_to_cart_form

If you plan to use the userfile input you can optionally specify an upload destination using the upload_directory parameter (noted above). You can specify an EE directory ID, or a server upload path if you're feeling adventurous. If no upload directory is specified, cartthrob will use the first upload directory it can find. CartThrob will add the upload file name, and directory as item_options (upload & upload_directory respectively). 

<input type="file" name="userfile" value="1" />

Examples

{!-- ADD A PRODUCT --}
<div class="store_block">
    <h2>Add T-Shirts</h2>
    {!-- outputting products stored in one of the "products" channels. These are exactly the same as normal 
        product channels, so the channel names may be different from what is listed below --}
    {exp:channel:entries channel="products" limit="10"}
        {!-- we're passing in the entry_id from the channel loop --}
        {exp:cartthrob:add_to_cart_form 
            entry_id="{entry_id}" 
            return="{template}/index"}

                    T-Shirt name: {title} Tee<br />
                    Quantity: <input type="text" name="quantity" size="5" value="" /> 
                    <input type="submit" value="Add to Cart">
                    <br />
                    Price: ${product_price}<br />
                    {!-- Some major magic happens below. This is the item_options tag.
                        Used in conjunction with a "Cartthrob Price Modifiers" field from your product channel, 
                        you can automatically create and populate input and select fields with the data from that custom field. 

                {exp:cartthrob:item_options entry_id="{entry_id}" }
                    {select} 
                        <option {selected} value="{option_value}">{option_name} {price}</option>
                    {/select}
                 {/exp:cartthrob:item_options}

        {/exp:cartthrob:add_to_cart_form}
    {/exp:channel:entries}
</div>

Buy Now

Top