CartThrob 9 documentation for ExpressionEngine commerce teams Visit CartThrob.com
Main docs
CartThrob.com

Add To Cart Form (tag pair)

add_to_cart_form builds a POST form that submits to CartThrob’s add_to_cart_action and adds one item (or an on-the-fly item) to the cart.

A video tutorial on this tag is available.

See also:

Parameters

In addition to these tag-specific parameters, this tag also supports global form parameters.

Common global parameters used with this tag include:

  • return
  • secure_return
  • error_handling
  • show_errors (default yes)
  • required
  • rules:*
  • action
  • secure_action
  • id
  • class
  • name
  • onsubmit
  • enctype
  • logged_out_redirect

Core Item Parameters

entry_id

Entry ID for the product being added.

entry_id="{entry_id}"
quantity

Quantity to add. If omitted or empty, the action defaults to 1.

quantity="1"
on_the_fly

Set to yes/y/true to add an item without a product entry.

on_the_fly="yes"

title

Title for an on-the-fly item (or to override item title in the add request).

title="Red T-Shirt"
language

Language used for CartThrob messages generated during this form flow.

language="en"

Price, Shipping, and Weight Parameters

price

Set a fixed item price for this submission.

price="9.95"

When price is provided as a tag parameter, it is encoded and takes precedence over user-entered price input.

shipping

Set a fixed item shipping amount for this submission.

shipping="4.95"

When shipping is provided as a tag parameter, it is encoded and takes precedence over user-entered shipping input.

weight

Set a fixed item weight for this submission.

weight="20"

When weight is provided as a tag parameter, it is encoded and takes precedence over user-entered weight input.

allow_user_price

Allow customer input named price to be used for the item price.

allow_user_price="yes"

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

Allow customer input named shipping to be used for item shipping.

allow_user_shipping="yes"

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

Allow customer input named weight to be used for item weight.

allow_user_weight="yes"

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

Tax and Shipping Exemption Parameters

no_tax

Marks this added item as non-taxable.

no_tax="yes"
tax_exempt

Alias of no_tax. Both map to the same behavior.

tax_exempt="yes"
no_shipping

Marks this added item as non-shippable.

no_shipping="yes"
shipping_exempt

Alias of no_shipping. Both map to the same behavior.

shipping_exempt="yes"

Item Metadata Parameters

license_number

When enabled, marks the item so license metadata is generated at checkout.

license_number="yes"
expiration_date

Sets expires item metadata (days from now) for purchased-item workflows.

expiration_date="365"
permissions

Sets item permissions metadata.

permissions="members|gold"
class

Overrides the CartThrob item class used when creating the cart item.

class="product"

Upload Parameters

upload_directory

Upload destination used when userfile is submitted. Can be an EE upload directory ID or path.

upload_directory="1"
enctype

Required when using file upload input (userfile).

enctype="multipart/form-data"

Upload input name must be userfile; otherwise CartThrob will not process the file.

Array-Style Parameters

item_options:*

Set item options directly as tag parameters.

item_options:shirt_size="XL"
item_options:shirt_color="Red"

Equivalent form fields:

<input type="text" name="item_options[shirt_size]" value="XL">
<input type="text" name="item_options[shirt_color]" value="Red">
meta:*

Set arbitrary item metadata keys.

meta:source="landing-page"
meta:campaign="spring-sale"

Equivalent form fields:

<input type="hidden" name="meta:source" value="landing-page">

Subscription-Compatible Parameters

The form supports subscription option payloads used by CartThrob’s subscription flows:

  • subscription
  • subscription_allow_modification
  • subscription_name
  • subscription_description
  • subscription_start_date
  • subscription_end_date
  • subscription_interval_units
  • subscription_interval_length
  • subscription_trial_interval_units
  • subscription_trial_interval_length
  • subscription_price
  • subscription_trial_price
  • subscription_total_occurrences
  • subscription_trial_occurrences
  • subscription_plan_id

Use direct subscription_* parameters when you need fully custom recurring settings per form. Use subscription_plan_id when the product should follow a predefined subscription plan.

Subscription examples

Example A: Direct subscription fields

{exp:cartthrob:add_to_cart_form
    entry_id="{entry_id}"
    subscription="yes"
    subscription_name="Monthly Coffee Club"
    subscription_description="Fresh beans delivered monthly"
    subscription_interval_units="months"
    subscription_interval_length="1"
    subscription_price="19.99"
    subscription_trial_price="9.99"
    subscription_trial_occurrences="1"
    subscription_total_occurrences="12"
    subscription_allow_modification="yes"
    return="store/view_cart"}
    <button type="submit">Start Subscription</button>
{/exp:cartthrob:add_to_cart_form}

Example B: Plan-based subscription

{exp:cartthrob:add_to_cart_form
    entry_id="{entry_id}"
    subscription_plan_id="3"
    return="store/view_cart"}
    <button type="submit">Add Subscription Plan</button>
{/exp:cartthrob:add_to_cart_form}

Plan-based setup is usually the simpler default when your subscription plan data already exists.

Variables

Inside the tag pair, CartThrob parses:

  • Global tag variables (including cart/customer/custom data values)
  • Form error variables (when using error_handling="inline")
  • Item option helper variables for the current entry_id

inventory:reduce

Use this variable to add inventory-reduction metadata for another entry during this add-to-cart flow.

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

Notes:

  • entry_id is required.
  • quantity is optional and defaults to 1.
  • You can include this variable multiple times in one form.

options:* helper pairs

You can pass options:* parameters and render encoded option choices in the tag body:

options:gift_wrap="none:No Wrap|basic:Basic Wrap|premium:Premium Wrap"

{options:gift_wrap selected="basic"}
    <label>
        <input type="radio" name="item_options[gift_wrap]" value="{option_value}"{checked}>
        {option_name}
    </label>
{/options:gift_wrap}

Available variables include {option_value}, {option_name}, {selected}, and {checked}.

Form Fields

Common posted fields for this form:

  • entry_id
  • quantity
  • title
  • language
  • price (when allow_user_price="yes")
  • shipping (when allow_user_shipping="yes")
  • weight (when allow_user_weight="yes")
  • item_options[...]
  • meta:*
  • userfile

Example field names:

<input type="hidden" name="entry_id" value="123">
<input type="text" name="quantity" value="1">
<input type="text" name="item_options[engraving]" value="For Alex">
<input type="hidden" name="meta:source" value="homepage">
<input type="file" name="userfile">

Behavior and Constraints

Form processing flow:

  1. Form rules are validated by CartThrob form builder.
  2. Customer info is saved.
  3. Item payload is assembled from encoded tag params and submitted fields.
  4. Item is added and optional metadata/options are attached.
  5. Success/error handling follows form builder behavior (return, secure_return, error_handling, show_errors).

Important implementation details:

  • tax_exempt and shipping_exempt are aliases for no_tax and no_shipping.
  • Fixed price/shipping/weight params override user-entered values.
  • show_errors defaults to yes unless set otherwise.
  • upload_directory is only used when a userfile upload is submitted.
  • Uploaded file info is added as item options:
    • upload (file name)
    • upload_directory (file path)
  • meta:* keys are merged into item metadata without replacing keys already set earlier in the action.
  • logged_out_redirect is honored for logged-out users.

Examples

Standard Product Form

{exp:channel:entries channel="products" limit="1"}
    {exp:cartthrob:add_to_cart_form
        entry_id="{entry_id}"
        return="store/view_cart"}
        <label>Quantity</label>
        <input type="text" name="quantity" value="1">
        <button type="submit">Add to Cart</button>
    {/exp:cartthrob:add_to_cart_form}
{/exp:channel:entries}

Donation / On-the-Fly Form

{exp:cartthrob:add_to_cart_form
    on_the_fly="yes"
    title="Donation"
    allow_user_price="yes"
    no_tax="yes"
    no_shipping="yes"
    return="store/view_cart"}
    <label>Donation Amount</label>
    <input type="text" name="price">

    <label>Note</label>
    <input type="text" name="item_options[donation_note]">

    <button type="submit">Add Donation</button>
{/exp:cartthrob:add_to_cart_form}

Upload with Add to Cart

{exp:cartthrob:add_to_cart_form
    entry_id="{entry_id}"
    upload_directory="1"
    enctype="multipart/form-data"
    return="store/view_cart"}
    <input type="file" name="userfile">
    <button type="submit">Add Item</button>
{/exp:cartthrob:add_to_cart_form}

Inventory Side-Effect

{exp:cartthrob:add_to_cart_form entry_id="{entry_id}" return="store/view_cart"}
    {inventory:reduce entry_id="6" quantity="1"}
    <button type="submit">Add to Cart</button>
{/exp:cartthrob:add_to_cart_form}