Update Cart Form (tag pair)

update_cart_form updates existing cart rows, removes rows, and can save customer/session cart data (customer fields, shipping option, and custom data) in the same submission.

A video tutorial on this tag is available..

See also:

• customer_info
• save_customer_info_form
• cart_items_info
• get_shipping_options
• item_options
• delete_from_cart_form
• Global Form Parameters

Row ID Indexing

Update fields for cart items must be keyed by the cart row ID.

Use {row_id} from cart_items_info:

<input type="text" name="quantity[{row_id}]" value="{quantity}">
<input type="checkbox" name="delete[{row_id}]">
<input type="text" name="item_options[{row_id}][notes]" value="{item_options:notes}">

For package sub-items, use a parent_row_id:sub_row_id index for updatable sub-item fields:

<input type="text" name="quantity[{row_id}:{sub:row_id}]" value="{sub:quantity}">
<input type="text" name="item_options[{row_id}:{sub:row_id}][size]" value="{sub:item_options:size}">

Parameters

Tag-level form data for update_cart_form includes return and secure_return.

Additional form behavior (validation, inline errors, required/rules, action overrides, etc.) comes from Global Form Parameters.

Commonly used with update_cart_form:

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

Advanced: encoded subscription payloads are accepted and cleaned during update processing (subscription, subscription_allow_modification, and subscription_* values such as subscription_plan_id, subscription_price, subscription_interval_units, etc.).

Variables

You may use Global Tag Variables.

update_cart_form parses globalVariables(true), so form/error variables are available when using inline error handling (for example {if errors_exist}, {errors}, {error:field}).

Use custom_data:* variables in tag content to repopulate custom data inputs.

Form Fields

• clear_cart
• quantity[{row_id}]
• delete[{row_id}]
• item_options[{row_id}][field_name]
• coupon_code
• shipping_option
• shipping[key]
• use_billing_info
• customer fields
• custom_data[key]

clear_cart

If present, clears all cart items in this submission.

<input type="submit" name="clear_cart" value="Clear Cart">

quantity[{row_id}]

Updates item quantity for that row.

<input type="text" name="quantity[{row_id}]" value="{quantity}">

Setting quantity to 0 removes the item.

delete[{row_id}]

Marks a row for removal. Any value works (checkbox is typical).

<input type="checkbox" name="delete[{row_id}]" value="yes">

item_options[{row_id}][field_name]

Updates item option/custom option data for a row.

<input type="text" name="item_options[{row_id}][notes]" value="{item_options:notes}">

coupon_code

Applies a coupon code after item updates are processed.

<input type="text" name="coupon_code" value="">

shipping_option

Updates the cart’s selected shipping option.

<select name="shipping_option">
    {exp:cartthrob:get_shipping_options}
        <option value="{option_value}"{selected}>{option_name}</option>
    {/exp:cartthrob:get_shipping_options}
</select>

shipping[key]

Updates cart shipping info values saved through save_customer_info.

Examples:

<input type="hidden" name="shipping[method]" value="ground">
<input type="hidden" name="shipping[eta]" value="5_days">

use_billing_info

When truthy, shipping customer fields are copied from billing fields during customer-info save processing.

<input type="checkbox" name="use_billing_info" value="1">

Customer fields

update_cart_form calls save_customer_info, so posted customer fields are saved in session/cart customer info.

Examples:

<input type="text" name="first_name" value="{customer_first_name}">
<input type="text" name="email_address" value="{customer_email_address}">
<input type="text" name="shipping_first_name" value="{customer_shipping_first_name}">
<input type="text" name="shipping_zip" value="{customer_shipping_zip}">

custom_data[key]

Saves cart custom data values.

<input type="text" name="custom_data[gift_message]" value="{custom_data:gift_message}">

Behavior and Constraints

Action flow:

1. Validate form settings/rules.
2. On validation failure, action completes through form builder for inline handling (clear_cart is explicitly preserved).
3. Save customer info and related posted customer/shipping/custom data.
4. If clear_cart is present, clear cart items and save cart.
5. Otherwise, update/remove item rows based on posted row-indexed fields.
6. If coupon_code is non-empty, apply coupon.
7. Run cart inventory checks.
8. Complete action with success/error redirect behavior.
9. Extension hooks run at start/end:
   • cartthrob_update_cart_start
   • cartthrob_update_cart_end

Important notes:

• clear_cart clears items only (it does not clear customer info/custom data).
• delete[{row_id}] internally forces that row quantity to 0.
• Quantity 0 removes the item row.
• Only existing cart row IDs are updated.
• Package sub-item updates use parent_row_id:sub_row_id keys.

Examples

Update Quantities and Delete Rows

{exp:cartthrob:cart_items_info}
    {if first_row}
        {exp:cartthrob:update_cart_form return="store/view_cart"}
    {/if}

    <p>{title}</p>
    <input type="text" name="quantity[{row_id}]" value="{quantity}" size="2">
    <label>
        <input type="checkbox" name="delete[{row_id}]" value="yes">
        Remove this item
    </label>

    {if last_row}
        <input type="submit" value="Update Cart">
        {/exp:cartthrob:update_cart_form}
    {/if}
{/exp:cartthrob:cart_items_info}

Update Cart + Shipping/Customer Data + Coupon

{exp:cartthrob:update_cart_form return="store/checkout" error_handling="inline"}
    {if errors_exist}
        <p>Please fix the highlighted errors.</p>
    {/if}

    {exp:cartthrob:customer_info}
        <input type="text" name="shipping_first_name" value="{customer_shipping_first_name}">
        <input type="text" name="shipping_last_name" value="{customer_shipping_last_name}">
        <input type="text" name="email_address" value="{customer_email_address}">
        <input type="text" name="shipping_zip" value="{customer_shipping_zip}">
    {/exp:cartthrob:customer_info}

    {exp:cartthrob:get_shipping_options}
        <label>
            <input type="radio" name="shipping_option" value="{option_value}"{selected}>
            {option_name}
        </label>
    {/exp:cartthrob:get_shipping_options}

    <input type="text" name="coupon_code" value="" placeholder="Coupon code">
    <input type="submit" value="Update Cart and Continue">
{/exp:cartthrob:update_cart_form}

Shipping Array + Use Billing Info

{exp:cartthrob:update_cart_form return="store/checkout"}
    <label>
        <input type="checkbox" name="use_billing_info" value="1">
        Use billing address for shipping
    </label>

    <input type="hidden" name="shipping[method]" value="ground">
    <input type="hidden" name="shipping[eta]" value="5_days">

    <input type="submit" value="Save Shipping Info">
{/exp:cartthrob:update_cart_form}