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

Global Tag Variables

This page documents variables returned by CartThrob’s shared globalVariables() pipeline.

These values are merged from:

  1. cart->info() (cart totals/count metadata),
  2. cart->customer_info() (customer/session fields),
  3. cart->custom_data() (custom_data:* keys),
  4. form_builder->form_variables() (form helper/error variables, form tags only).

In template output, customer fields are available as both:

  • raw keys (for example {first_name}),
  • prefixed keys (for example {customer_first_name}).

Legacy note: Older docs referenced create_token_form, update_recurrent_billing_form, and delete_recurrent_billing_form. Those are not current callable tags in this codebase. Use the vault form tags instead: add_vault_form, update_vault_form, and delete_vault_form.

Cart Info Variables

These variables output data from the current cart. Each variable is available in the tag pairs listed above.

cart_subtotal

Cart total minus shipping and tax, without discounts applied

{cart_subtotal}
$11.95

cart_subtotal_plus_tax / cart_subtotal:plus_tax

Subtotal plus tax (formatted).

{cart_subtotal_plus_tax}
{cart_subtotal:plus_tax}
$13.90

cart_tax

The amount of tax calculated for all items in the cart.

{cart_tax}
$1.95

cart_shipping

Cost of shipping for all items in the cart

{cart_shipping}
$13.95

cart_shipping_plus_tax / cart_shipping:plus_tax

Shipping amount including shipping tax (formatted).

{cart_shipping_plus_tax}
{cart_shipping:plus_tax}
$14.95

cart_discount

Discounted amount for all items in the cart

{cart_discount}
$10.95

cart_total

Final cart total (subtotal + tax + shipping - discount), formatted.

{cart_total}
$13.95

cart_total_plus_tax / cart_total:plus_tax

Alias values for total (formatted).

{cart_total_plus_tax}
{cart_total:plus_tax}
$13.95

cart_subtotal_numeric

Cart total minus shipping and tax, without discounts applied, without any number formatting. Useful in conditionals.

{cart_subtotal_numeric}
11.95

cart_tax_numeric

The amount of tax calculated for all items in the cart, without any number formatting. Useful in conditionals.

{cart_tax_numeric}
1.95

cart_shipping_numeric

Cost of shipping for all items in the cart, without any number formatting. Useful in conditionals.

{cart_shipping_numeric}
13.95

cart_discount_numeric

Discounted amount for all items in the cart, without any number formatting. Useful in conditionals.

{cart_discount_numeric}
10.95

cart_total_numeric

Final cart total without number formatting. Useful in conditionals/calculations.

{cart_total_numeric}
13.95

cart_id

Active cart session identifier.

{cart_id}
abc123xyz

cart_tax_rate

The current tax rate value used in cart tax calculations.

{cart_tax_rate}
0.07

cart_tax_name

The name of the current tax rate being used to calculate the cart total.

{cart_tax_name}
California

cart_weight

Total combined cart weight.

{cart_weight}
12.5

total_items

The total number of items in the cart (number of items X quantity)

{total_items}
12

total_unique_items

The total number of unique items in the cart. This ignores quantities, and looks solely at the total number of unique products.

{total_unique_items}
2

cart_entry_ids

A pipe delimited list of product entry IDs currently in the cart

{cart_entry_ids}
1|12|123|1234

shipping_option

The user’s selected shipping option, if applicable to the shipping plugin you are using.

{shipping_option}
UPS-By Weight Global Rate

Customer Info Variables

These variables expose customer/session values saved into the current cart using form tags such as save_customer_info_form, update_cart_form, and checkout_form.

Each key listed in global form fields (customer_info_defaults) has a matching customer_* output variable.

The same values are also available in unprefixed form (for example {first_name} in addition to {customer_first_name}), but the customer_* prefix is generally recommended in templates to avoid name collisions.

customer_first_name

{customer_first_name}
King

customer_last_name

{customer_last_name}
Randor

customer_address

{customer_address}
1 Miro Way

customer_address2

{customer_address2}
Turret 1

customer_city

{customer_city}
Eternia

customer_state

{customer_state}
ET

customer_zip

{customer_zip}
63303

customer_company

{customer_company}
Mattel

customer_country

{customer_country}
United States

customer_country_code

{customer_country_code}
USA

customer_region

{customer_region}
Trondheim

customer_phone

{customer_phone}
555-555-5555

customer_email_address

{customer_email_address}
[email protected]

customer_shipping_first_name

{customer_shipping_first_name}
Queen

customer_shipping_last_name

{customer_shipping_last_name}
Marlena

customer_shipping_phone

{customer_shipping_phone}
555-555-5555

customer_shipping_address

{customer_shipping_address}
1 Miro Way

customer_shipping_address2

{customer_shipping_address2}
Spire 12

customer_shipping_city

{customer_shipping_city}
Eternia

customer_shipping_state

{customer_shipping_state}
ET

customer_shipping_zip

{customer_shipping_zip}
63303

customer_shipping_country

{customer_shipping_country}
United States

customer_shipping_country_code

{customer_shipping_country_code}
USA

customer_shipping_company

{customer_shipping_company}
Mattel

customer_shipping_region

{customer_shipping_region}
North

customer_ip_address

{customer_ip_address}
192.168.1.1

customer_weight_unit

{customer_weight_unit}
lbs

customer_language

{customer_language}
en

customer_use_billing_info

{customer_use_billing_info}
Yes

customer_description

{customer_description}
Equipment Purchase

customer_card_type

{customer_card_type}
Visa

customer_expiration_month

{customer_expiration_month}
01

customer_expiration_year

{customer_expiration_year}
12

customer_po_number

{customer_po_number}
123456

customer_card_code

{customer_card_code}
123

customer_CVV2

{customer_CVV2}
1234

customer_issue_number

{customer_issue_number}
123

customer_transaction_type

{customer_transaction_type}
Digital Goods

customer_bank_account_number

{customer_bank_account_number}
123456789

customer_bank_account_name

{customer_bank_account_name}
ACME Corp

customer_bank_name

{customer_bank_name}
CartThrob Bank

customer_check_type

{customer_check_type}
Commercial

customer_account_type

{customer_account_type}
Checking

customer_routing_number

{customer_routing_number}
0812345

customer_begin_month

{customer_begin_month}
02

customer_begin_year

{customer_begin_year}
09

customer_bday_month

{customer_bday_month}
08

customer_bday_day

{customer_bday_day}
02

customer_bday_year

{customer_bday_year}
75

customer_currency_code

{customer_currency_code}
USD

customer_shipping_option

{customer_shipping_option}
Ground

customer_gateway

{customer_gateway}
stripe

customer_success_return

{customer_success_return}
/mysite/success

customer_cancel_return

{customer_cancel_return}
/mysite/fail

customer_username

{customer_username}
kingrandor

customer_screen_name

{customer_screen_name}
King Randor

custom_data:your_data_field_name

Prints out custom data saved in the save_customer_info_form. If the key does not exist, output is blank.

{custom_data:your_data_field_name}

Form Helper Variables

These are available in CartThrob form tags that parse with globalVariables(true) (for example checkout_form, update_cart_form, save_customer_info_form, add_vault_form).

Error state variables

  • errors_exist
  • global_errors_exist
  • field_errors_exist
  • global_errors:count
  • field_errors:count
  • error:field_name (per-field message)

Examples:

{if errors_exist}
    There were validation errors.
{/if}

{if error:email_address}
    <span class="error">{error:email_address}</span>
{/if}

Nested-field alias example:

{error:item_options:product_size}

Error tag pairs

  • {errors}{/errors}
  • {global_errors}{/global_errors}
  • {field_errors}{/field_errors}

Inside these pairs:

  • {error}
  • {field}
  • {error:count}
  • {error:total_results}
  • {if global_error}
  • {if field_error}
  • {if first_error}
  • {if last_error}

Helper variables from form builder

  • {encode name="field_name"}: encoded input name helper.
  • {encode name="field_name" value="field_value"}: encoded input value helper.
  • {if captcha}...{/if}: populated only when captcha is enabled for the form context.
  • Submitted values are also reflected as variables so forms can repopulate fields after validation failures.

Parameters

variable_prefix

This parameter allows you to set a custom prefix for variables parsed by the tag body. This is useful to avoid collisions when nesting multiple tag pairs.

variable_prefix="custom_prefix:"

{exp:cartthrob:checkout_form variable_prefix="custom_prefix:"}
    {if custom_prefix:no_results}
        NO RESULTS
    {/if}
    {custom_prefix:cart_total}
{/exp:cartthrob:checkout_form}