Global Form Tag Parameters and Fields

This page documents shared behavior for CartThrob form tags that use the CartThrob form_builder pipeline.

Use this page as the baseline for:

• common form parameters,
• shared validation and error behavior,
• shared customer/shipping/custom-data input names,
• and helper variables available while rendering form tags.

Form tags can still add their own tag-specific parameters. See also:

• add_coupon_form
• add_to_cart_form
• cart_form
• checkout_form
• delete_from_cart_form
• download_file_form
• get_live_rates_form
• multi_add_to_cart_form
• save_customer_info_form
• update_cart_form
• add_vault_form
• update_vault_form
• delete_vault_form
• global_tag_variables

Parameters

These parameters are accepted by CartThrob form tags through shared form-builder behavior.

• id
• class
• name
• onsubmit
• enctype
• action
• return
• secure_return
• secure_action
• required
• rules:your_field
• show_errors
• error_handling
• form_idempotency
• logged_out_redirect
• variable_prefix
• language
• derive_country_code
• shipping_option

Universal Form Parameters

These are shared across CartThrob form tags using form_builder.

HTML Parameters

id

CSS id for the generated <form> tag.

id="checkout_form"

class

CSS class for the generated <form> tag.

class="checkout"

name

HTML name attribute for the generated <form> tag.

name="checkout_form"

onsubmit

Optional JavaScript callback run on submit.

onsubmit="return validateCheckout()"

enctype

Optional form encoding type.

Use this when your form submits file inputs.

enctype="multipart/form-data"

Submission and Redirect Parameters

action

Overrides the form submit URL.

If omitted, CartThrob submits to the current page URL.

action="/en/cart/checkout"

return

Target URL after successful/failed action completion.

If omitted, action flow falls back to the current URI.

return="store/order_complete"

secure_return

If truthy, return URL is forced to HTTPS.

secure_return="yes"

secure_action

If truthy, submit action URL is forced to HTTPS.

secure_action="yes"

Validation and Error Parameters

required

Pipe-delimited required fields for this form submission.

required="first_name|last_name|email_address"

rules:your_field

Per-field validation rules (ExpressionEngine/CodeIgniter rule syntax).

rules:email_address="required|valid_email"
rules:item_options[product_size]="required"

Rule availability depends on the ExpressionEngine/CodeIgniter validation stack in your install. Commonly used rules include:

• required
• valid_email
• min_length[n]
• max_length[n]
• matches[field]
• numeric
• integer
• alpha
• alpha_numeric
• alpha_dash

show_errors

Controls whether CartThrob shows the default error response when errors exist.

Default: yes.

show_errors="yes"
show_errors="no"

error_handling

Set to inline to keep the user on the same template and render errors using inline error variables.

error_handling="inline"

Idempotency Parameter

form_idempotency

Per-form idempotency toggle.

When CartThrob idempotency is enabled in settings, this defaults to yes. Set to no only when duplicate-submit protection should be bypassed.

form_idempotency="yes"
form_idempotency="no"

Guarded or Form-Specific Shared Parameters

These are commonly used in form flows, but are not universal in the same way as the parameters above.

logged_out_redirect

Redirect target used by form tags that explicitly call logged-out guard logic.

logged_out_redirect="account/login"

Notes:

• This works only for guarded form tags.
• It is not processed by form_builder itself.

variable_prefix

Tag-level helper to prefix parsed variables and avoid collisions.

variable_prefix="checkout_"

This applies to variables parsed by the tag body, for example:

{checkout_errors_exist}
{checkout_error:first_name}

language

Supported by forms that include language in their posted form data. Used by CartThrob language handling in action flow.

language="english"
language="en"

derive_country_code

Accepted by some form tags for compatibility.

Current implementation also auto-derives country_code when country is posted and country_code is missing, so this parameter is usually not required.

derive_country_code="yes"

shipping_option

Form-specific parameter (not universal). Most commonly used in shipping-rate form flows.

shipping_option="ground"

Form Parameter Support Matrix

This matrix focuses on parameters that vary by form tag.

Parameters that vary by form tag

Shared form-builder capabilities across these tags

• action can be configured through shared form-builder handling.
• required and rules:* are shared validation configuration features.
• error_handling and form_idempotency are shared form-builder behaviors.

Action-level enforcement can still vary by tag/action implementation, so shared capability does not always mean identical runtime behavior.

shipping_option can also be submitted as a normal input field in many customer-info flows, even when not supported as a tag parameter.

Form Fields

Input fields gather customer and checkout data in CartThrob forms.

Two core patterns:

Standard Inputs

<input type="text" name="first_name" value="{first_name}">

Custom Data Inputs

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

When CartThrob saves customer information, standard input names map to known customer fields, while custom_data[key] maps to custom cart data.

Common

Current standard customer field keys (from customer_info_defaults):

• first_name
• last_name
• address
• address2
• city
• state
• zip
• country
• country_code
• company
• phone
• email_address
• ip_address
• description
• use_billing_info
• shipping_first_name
• shipping_last_name
• shipping_phone
• shipping_address
• shipping_address2
• shipping_city
• shipping_state
• shipping_zip
• shipping_country
• shipping_country_code
• shipping_company
• shipping_region
• CVV2
• card_type
• expiration_month
• expiration_year
• begin_month
• begin_year
• bday_month
• bday_day
• bday_year
• currency_code
• language
• shipping_option
• weight_unit
• region
• success_return
• cancel_return
• gateway
• po_number
• card_code
• issue_number
• transaction_type
• bank_account_number
• bank_account_name
• bank_name
• check_type
• account_type
• routing_number
• username
• screen_name

Advanced / Payment / Shipping / Custom Data

Additional supported input patterns in shared save flow:

• custom_data[key] (saved to cart custom data)
• shipping_option (saved as shipping info option)
• shipping[key] (saved to shipping info array)

Examples:

<input type="text" name="shipping_option" value="ground">
<input type="text" name="shipping[address_type]" value="residential">
<input type="text" name="custom_data[po_reference]" value="PO-1234">

Behavior notes:

• If country_code is missing but country is posted, CartThrob derives country_code automatically.
• If use_billing_info is truthy, shipping customer fields are copied from billing fields during save flow.

Where is the credit_card_number field?

credit_card_number is intentionally not saved by this flow.

CartThrob avoids storing full card numbers in session/customer data for security reasons.

Inline Errors

When error_handling="inline" is used, errors can be rendered in context inside the same template.

To keep values on failed validation, populate inputs with template variables:

<input type="text" name="first_name" value="{first_name}">

Available conditionals and variables:

• {if errors_exist}
• {if global_errors_exist}
• {if field_errors_exist}
• {if error:your_field}
• {errors}{/errors}
• {global_errors}{/global_errors}
• {field_errors}{/field_errors}
• {error:your_field_name}

{if field_errors_exist}

True when at least one field-scoped error exists.

{if field_errors_exist}
<ul class="errors">
    {field_errors}
    <li>{error}</li>
    {/field_errors}
</ul>
{/if}

{if global_errors_exist}

True when at least one global (non-field) error exists.

{if global_errors_exist}
<ul class="errors">
    {global_errors}
    <li>{error}</li>
    {/global_errors}
</ul>
{/if}

{if errors_exist}

True when any error exists.

{if errors_exist}
There were some errors submitting your form.
{/if}

{if error:your_field}

True when a specific field has an error.

<input type="text" name="first_name" value="{first_name}">
{if error:first_name}
<p class="error">{error:first_name}</p>
{/if}

{error:your_field_name}

Outputs the error text for a specific field.

<label for="first_name"><span class="error">{error:first_name}</span></label>
<input type="text" id="first_name" name="first_name" value="{first_name}">

Array-style field example:

<label for="item_options[product_size]"><span class="error">{error:item_options[product_size]}</span></label>
<input type="text" id="item_options[product_size]" name="item_options[product_size]" value="{item_options:product_size}">

{field_errors}{/field_errors}

Lists field-scoped errors.

{field_errors}
<p class="error" id="error_{field}">{error}</p>
{/field_errors}

{global_errors}{/global_errors}

Lists global (non-field) errors.

{global_errors}
<p class="error">{error}</p>
{/global_errors}

{errors}{/errors}

Lists all errors.

{errors}
<p class="error">{error}</p>
{/errors}

Tag Pair Variables

The three error tag pairs (errors, global_errors, field_errors) provide:

error

{error}

field

{field}

error:count

{error:count}

error:total_results

{error:total_results}

{if global_error}

{if global_error}

{if field_error}

{if field_error}

{if first_error}

{if first_error}

{if last_error}

{if last_error}

Advanced Form Helpers

These helpers are part of shared form behavior and are useful when building custom markup.

options:* parameter helpers

You can pass option maps using options:field_name and render encoded values via the generated options pair.

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

{options:gift_wrap}
<option value="{option_value}">{option_name}</option>
{/options:gift_wrap}

{encode ...} helper variables

You can request encoded input names/values while rendering the form tag body.

{encode name="shipping_option"}
{encode name="shipping_option" value="ground"}

{if captcha} helper block

When a form has captcha enabled, this block is populated with captcha data.

{if captcha}
    <div class="captcha">{captcha}</div>
{/if}

Internal Hidden Transport Fields

CartThrob form output automatically injects internal hidden fields including:

• ACT (action id)
• RET (current URI snapshot)
• URI (current URI)
• FRM (form hash)
• RLS (encoded rules payload)
• ERR (encoded show-errors flag)

These are managed internally by form_builder and should not be manually edited.

Vault Form Tags

The following vault form tags are now documented and use the same shared form-builder concepts described on this page.

1. add_vault_form: Create a saved payment method (vault token) for a member.
2. update_vault_form: Update an existing member-owned vault record.
3. delete_vault_form: Delete an existing member-owned vault record.

These vault forms are typically used in account/checkout-adjacent flows for returning customers.