Multi Add To Cart Form (tag pair)

multi_add_to_cart_form adds multiple items to the cart in one submission.

See also:

• add_to_cart_form
• update_cart_form
• item_options
• cart_items_info
• Global Form Parameters

Array Indexes

Each row in the submission is identified by a shared array key.

Any unique key is valid (1, abc, 10-10) as long as you use the same key for all fields of that row:

<input type="hidden" name="entry_id[abc]" value="123" />
<input type="text" name="quantity[abc]" value="1" />
<input type="text" name="item_options[abc][notes]" value="Gift wrap" />

Processing is driven by entry_id[key] with quantity[key]. Rows with missing, non-numeric, or <= 0 quantities are skipped.

Parameters

In addition to the parameters below, this tag supports Global Form Parameters.

Common global parameters used here:

• return
• secure_return
• language
• error_handling
• show_errors
• required
• rules:*
• action
• secure_action
• id
• class
• name
• onsubmit
• logged_out_redirect

Tag-level options handled by multi_add_to_cart_form:

• allow_user_price
• allow_user_shipping
• allow_user_weight
• on_the_fly
• no_tax
• tax_exempt
• no_shipping
• shipping_exempt
• permissions

allow_user_price

Allows each row to use price[key] input.

allow_user_price="yes"

allow_user_shipping

Allows each row to use shipping[key] input.

allow_user_shipping="yes"

allow_user_weight

Allows each row to use weight[key] input.

allow_user_weight="yes"

on_the_fly

Treats all rows as on-the-fly items (not normal product class rows unless class overrides it).

on_the_fly="yes"

no_tax

Applies non-taxable behavior to all rows in this submission.

no_tax="yes"

tax_exempt

Alias of no_tax.

tax_exempt="yes"

no_shipping

Applies non-shippable behavior to all rows in this submission.

no_shipping="yes"

shipping_exempt

Alias of no_shipping.

shipping_exempt="yes"

permissions

Adds permissions metadata to each added row.

permissions="members|gold"

Variables

See Global Tag Variables.

This tag also provides encoded helper values used by official examples:

• {encoded:yes}
• {encoded:no}

Use these with per-row encoded fields like pNTX[key] and pNSH[key].

Form Fields

• entry_id[x]
• quantity[x]
• title[x]
• price[x]
• shipping[x]
• weight[x]
• item_options[x][field_name]
• pNTX[x]
• pNSH[x]
• license_number[x]
• customer/custom data fields

entry_id[x]

Required product entry ID for each row.

<input type="hidden" name="entry_id[{count}]" value="{entry_id}" />

quantity[x]

Quantity for each row.

<input type="text" name="quantity[{count}]" value="1" />

Rows with invalid or <= 0 quantities are not added.

title[x]

Optional title per row. Common for on-the-fly rows.

<input type="text" name="title[{count}]" value="My Product" />

price[x]

Per-row price. Used when allow_user_price="yes" or on_the_fly="yes".

<input type="text" name="price[{count}]" value="9.95" />

shipping[x]

Per-row shipping value. Used when allow_user_shipping="yes" or on_the_fly="yes".

<input type="text" name="shipping[{count}]" value="4.95" />

weight[x]

Per-row weight value. Used when allow_user_weight="yes" or on_the_fly="yes".

<input type="text" name="weight[{count}]" value="20" />

item_options[x][field_name]

Per-row item options/custom option values.

<input type="text" name="item_options[{count}][notes]" value="Gift message" />

pNTX[x]

Per-row encoded no-tax flag.

<input type="hidden" name="pNTX[{count}]" value="{encoded:yes}" />

pNSH[x]

Per-row encoded no-shipping flag.

<input type="hidden" name="pNSH[{count}]" value="{encoded:yes}" />

license_number[x]

Marks row for license metadata when truthy.

<input type="hidden" name="license_number[{count}]" value="1" />

Customer/custom data fields

Because the action calls save_customer_info, you can include customer and custom data fields in this form.

Examples:

<input type="text" name="email_address" value="{customer_email_address}" />
<input type="text" name="shipping_zip" value="{customer_shipping_zip}" />
<input type="text" name="custom_data[gift_note]" value="{custom_data:gift_note}" />

Behavior and Constraints

Action flow:

1. Validate form settings/rules.
2. Save customer info/custom data from posted fields.
3. Iterate entry_id[] rows and build row data from matching keys.
4. Add valid rows to cart.
5. Run cart inventory checks.
6. Complete action with success/error redirect.

Important constraints:

• Configured items are not supported by this action (explicit implementation note).
• Rows with invalid/non-positive quantity are skipped.
• Per-row tax/shipping exemptions are handled via pNTX[] / pNSH[].
• No file-upload handling exists in this action.

Examples

Basic Multi-Add Form

{exp:cartthrob:multi_add_to_cart_form return="cart_examples/single_page_checkout"}
    {exp:channel:entries channel="products" limit="5"}
        Product Name: {title} {product_price}<br>
        <input type="hidden" name="entry_id[{count}]" value="{entry_id}" />
        Note: <input type="text" name="item_options[{count}][notes]" /><br>
        Quantity: <input type="text" name="quantity[{count}]" value="1" /><br><br>

        {if count == total_results}
            <input type="submit" value="Add to Cart" />
        {/if}
    {/exp:channel:entries}
{/exp:cartthrob:multi_add_to_cart_form}

Multi-Add With Per-Row No-Shipping / No-Tax

{exp:channel:entries channel="products" limit="5"}
    {if count == 1}
        {exp:cartthrob:multi_add_to_cart_form return="cart_examples/single_page_checkout"}
    {/if}

    <input type="hidden" name="entry_id[{count}]" value="{entry_id}" />
    <input type="text" name="quantity[{count}]" value="1" />

    {if no_shipping == 'Yes'}
        <input type="hidden" name="pNSH[{count}]" value="{encoded:yes}" />
    {/if}
    {if no_tax == 'Yes'}
        <input type="hidden" name="pNTX[{count}]" value="{encoded:yes}" />
    {/if}

    {if count == total_results}
        <input type="submit" value="Add Selected Items" />
        {/exp:cartthrob:multi_add_to_cart_form}
    {/if}
{/exp:channel:entries}