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

Checkout Form (tag pair)

checkout_form outputs an HTML checkout form that posts to checkout_action, saves customer data, validates required fields, and starts payment processing.

A video tutorial on this tag is available.

See also:

Parameters

In addition to the parameters listed here, this tag also supports Global Form Parameters such as return, secure_return, error_handling, show_errors, required, rules:*, action, secure_action, id, class, name, onsubmit, enctype, and logged_out_redirect.

required

Adds required validation rules for additional fields on this checkout form.

Use a pipe-delimited list:

required="first_name|last_name|email_address"

Gateway-required fields are validated automatically. To exclude specific gateway-required fields, use the not prefix:

required="not first_name|last_name"

cart_empty_redirect

If the cart is empty when the tag renders, the customer is redirected to this path.

cart_empty_redirect="cart/index"

gateway

Sets the payment gateway short name for this checkout form.

  • If gateway selection is disabled in CartThrob settings, this parameter is ignored.

  • You can also post gateway from an input field (for example, from gateway_select).

    gateway=”authorize_net”

gateway_method

Sets an optional gateway-specific method (for gateways that support it).

gateway_method="ideal"

allow_user_price

Allows a posted price form field to override calculated cart subtotal during checkout.

allow_user_price="yes"

price

Sets a fixed subtotal override for this checkout form.

price="100"

allow_user_shipping

Allows a posted shipping form field to override calculated shipping during checkout.

allow_user_shipping="yes"

shipping

Sets a fixed shipping override for this checkout form.

shipping="15"

tax

Sets a fixed tax override for this checkout form.

tax="8.25"

country_code (legacy note)

country_code is commonly used as an input field value (for example, name="country_code") and saved through customer-info handling.

In current implementation, it is not a dedicated encoded checkout-form parameter like price, shipping, or tax.

expiration_date

When orders are saved as channel entries, sets entry expiration in days from now.

expiration_date="365"

create_user

Enables member creation during checkout.

create_user="yes"

When enabled, include create-member fields in your form (username, email_address, optional screen_name, password, password_confirm).

group_id

Sets the member group for create_user="yes".

  • Values below 5 are forced to 5.

  • role_id is accepted as an alias in current code.

    group_id=”6”

force_processing

Skips immediate card charge and marks order as processing.

force_processing="yes"

force_vault

Forces vault creation even when no subscription is present.

force_vault="yes"

vault_id

Uses an existing vault record for payment.

  • Vault ownership is validated against the current member.

  • When vault_id is used, render {vault_fields} instead of {gateway_fields}.

    vault_id=”1”

member_id

Admin checkout parameter: checkout on behalf of another member (allowed admin groups only).

member_id="123"

order_id

Completes an existing order in processing status. If this is set, member_id is ignored.

authorized_redirect, failed_redirect, declined_redirect, processing_redirect

Optional status-specific return paths used after checkout completion.

authorized_redirect="store/order/success"
declined_redirect="store/order/declined"
failed_redirect="store/order/failed"
processing_redirect="store/order/processing"

custom_js

Set to yes/true to disable gateway-provided auto-injected JavaScript (form_extra) so you can provide your own implementation.

custom_js="yes"

Variables

In addition to the variables below, you can use Global Tag Variables, including cart/customer/custom-data values and form error values when inline error handling is used.

{gateway_fields}

Outputs the HTML fields required by the active gateway.

If gateway selection is enabled, this reflects the selected gateway context.

{vault_fields}

When vault_id is used, this outputs gateway vault fields for tokenized payment flows.

{captcha}

When guest checkout captcha is enabled, outputs the captcha image markup.

Error Variables

When using inline error handling, these are available inside the form:

  • errors_exist
  • field_errors_exist
  • global_errors_exist
  • {errors}...{/errors}
  • {field_errors}...{/field_errors}
  • {global_errors}...{/global_errors}
  • error:field_name (per-field message)

Conditionals

{if captcha}

True when captcha is required for this checkout context.

{if captcha}
    <p>Please enter the word in the image:</p>
    <p>{captcha}</p>
    <input type="text" name="captcha" />
{/if}

{if errors_exist}

True when the previous submit failed validation/processing and errors are available.

{if errors_exist}
    {errors}
        <p>{if field_error}<strong>{field}:</strong>{/if} {error}</p>
    {/errors}
{/if}

{if no_results} (legacy compatibility)

Legacy docs referenced this conditional, but checkout form behavior is currently controlled by cart_empty_redirect or your own outer cart checks (for example with total_items_count).

Use cart_empty_redirect when you want an automatic redirect for empty carts.

Form Fields

use_billing_info

If truthy, posted shipping fields are copied from billing fields during customer-info save.

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

price (form field)

Posted price is used only when allow_user_price is enabled.

<input type="text" name="price" value="11" />

shipping (form field)

Posted shipping is used only when allow_user_shipping is enabled.

<input type="hidden" name="shipping" value="10" />

tax (form field)

Posts a tax override value for this checkout request.

<input type="hidden" name="tax" value="2.50" />

coupon_code

Adds a coupon code during checkout submission.

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

shipping_option and shipping[key]

These are saved as shipping info during checkout save flow.

<input type="hidden" name="shipping_option" value="ground" />
<input type="hidden" name="shipping[service_code]" value="ground" />

custom_data[key]

Stores custom cart data values on submit.

<input type="hidden" name="custom_data[source]" value="newsletter" />

meta:some_key

For Stripe gateways, posted fields prefixed with meta: are forwarded as Stripe metadata.

<input type="hidden" name="meta:ReferredBy" value="Wanda Sellalot" />
<input type="text" name="meta:GiftFor" placeholder="Gift Recipient Name" />

Behavior and Constraints

  1. Checkout form validates inventory before rendering. If inventory is invalid, the tag errors immediately.
  2. If cart_empty_redirect is provided and cart is empty, customer is redirected.
  3. Gateway selection logic:
    • uses configured default gateway by default
    • respects gateway only when gateway selection is allowed
    • can use customer-selected posted gateway
  4. save_customer_info() runs during checkout action unless bypassed by admin/order-specific flows.
  5. Required fields come from gateway-required fields plus your required/rules:* settings.
  6. coupon_code is applied before payment processing.
  7. Redirect behavior:
    • return is standard fallback
    • status redirects (authorized_redirect, processing_redirect, declined_redirect, failed_redirect) are supported.
  8. vault_id is ownership-checked; invalid vault IDs are ignored.
  9. custom_js="yes" disables auto gateway JS injection so custom integration can control gateway scripts.
  10. Subscription-compatible subscription_* encoded parameters are accepted by checkout form/action and are processed during checkout subscription handling.

Examples

Standard checkout with gateway fields:

{exp:cartthrob:checkout_form
    id="checkout_form"
    class="form-horizontal"
    return="store/order_info"
}
    {gateway_fields}
    <input type="submit" value="Complete Checkout" />
{/exp:cartthrob:checkout_form}

Checkout with inline errors and coupon field:

{exp:cartthrob:checkout_form
    error_handling="inline"
    required="first_name|last_name|email_address"
    return="store/order_info"
}
    {if errors_exist}
        {errors}
            <p>{if field_error}<strong>{field}:</strong>{/if} {error}</p>
        {/errors}
    {/if}

    {gateway_fields}
    <input type="text" name="coupon_code" />
    <input type="submit" value="Checkout" />
{/exp:cartthrob:checkout_form}

Create member during checkout:

{exp:cartthrob:checkout_form
    create_user="yes"
    group_id="6"
    return="store/order_info"
}
    {gateway_fields}
    <input type="text" name="username" />
    <input type="text" name="email_address" />
    <input type="text" name="screen_name" />
    <input type="password" name="password" />
    <input type="password" name="password_confirm" />
    <input type="submit" value="Checkout" />
{/exp:cartthrob:checkout_form}

Vault checkout example:

{exp:cartthrob:checkout_form
    vault_id="1"
    force_vault="yes"
    return="store/order_info"
}
    {vault_fields}
    <input type="submit" value="Charge Saved Method" />
{/exp:cartthrob:checkout_form}