Template Tags: Checking Out

You can view a tutorial on checking out here.

See also Checkout Amounts and Payment Review and Custom checkout JavaScript.

Checkout Tags

Core Checkout Submission

• checkout_form Submit the cart for final validation, order creation, and payment processing.
• checkout_price_change Display and continue a verified changed-total notice when checkout_form uses template presentation.
• gateway_fields_url Return an endpoint URL for dynamically loading gateway fields through AJAX.
• check_cc_number_errors Validate a credit-card number/card type pair and output legacy helper error variables.

Use submitted_order_info on the checkout return/result page to display success/failure state, order IDs, transaction references, and gateway feedback.

Gateway Selection and Dynamic Gateway Fields

• gateway_select Output a gateway selector for checkout when gateway choice is enabled.
• selected_gateway_fields Output fields for the currently selected gateway.
• gateway_fields Output gateway-specific HTML fields for the currently active gateway.

Saved Payment Methods (Vault)

• vaults List saved payment methods (vault records), commonly used to select a member’s primary vault for checkout.
• add_vault_form Create a saved payment method/token for future checkout use.
• update_vault_form Edit an existing member-owned saved payment method.
• delete_vault_form Remove an existing member-owned saved payment method.
• save_vault_checkbox Output a checkbox input (VLT) to request saving the payment method in checkout.
• save_vault_field_value Output the encrypted vault-save token value used by VLT inputs.

These are typically account/checkout-adjacent flows used by returning customers.

Shipping and Customer Data Before Checkout

• update_cart_form Save shipping choices and customer fields before final checkout submission (also used on Cart page).
• customer_info Output saved customer data for prefilled shipping/billing forms (also used on Cart page).
• save_customer_info_form Save customer/session values without modifying cart line items (also used on Cart page).
• save_customer_info Legacy immediate helper to validate/save customer data before checkout; prefer save_customer_info_form for modern flows.
• is_saved Check whether any customer-info data is already stored in cart session.
• get_shipping_options Output available shipping options from the active shipping plugin.
• selected_shipping_option Output the selected shipping option value.
• state_select Output a state/province select field used in address capture.
• country_select Output a country select field used in address capture.

Checkout Totals, Coupons, and Cart Review

• cart_items_info Output cart line-item rows for checkout review (also used on Cart page).
• cart_subtotal Output the cart subtotal for checkout summaries (also used on Cart page).
• cart_subtotal_plus_shipping Output subtotal plus shipping for pre-tax checkout summaries (also used on Cart page).
• cart_shipping Output shipping totals in checkout summaries (also used on Cart page).
• cart_tax Output tax totals in checkout summaries (also used on Cart page).
• cart_discount Output currently applied discount totals.
• cart_total Output final total in checkout summaries (also used on Cart page).
• total_items_count Output total quantity count for checkout/cart indicators (also used on Cart page).
• unique_items_count Output unique line-item count for summaries (also used on Cart page).
• add_coupon_form Submit coupon/voucher codes during checkout.

Order Completion and Post-Checkout Display

• submitted_order_info Output order-complete and order-failure data after checkout submission.
• order_items Output purchased line items on order confirmation, invoice, or account pages (also used on Cart page).
• view_setting Output configured store settings used by checkout/order templates.
• view_encrypted_string Encrypt values (for example order IDs) used in secure invoice/order links.
• view_decrypted_string Decrypt values from secure links for order/invoice display.

Overview

Whether you use a multi-page checkout or a single-page checkout, CartThrob is generally flexible about page structure. The important parts are process order and final-step data capture.

1. Checkout is the last step in the cart process.
2. Credit card numbers are not stored in session. Capture card data at the final checkout step.

Checkout completes the customer purchase workflow and begins payment processing. In standard flows, checkout:

• validates required checkout/gateway fields
• creates an order entry in the orders channel
• can create a new member account (when registration fields are included)
• sends data to the configured payment gateway (if used)
• runs checkout-related extension hooks

Checkout is not only about payment capture. It is the final transaction step where customer/order data is validated, saved, and passed to downstream payment and order systems. Aside from validation/payment failures, it is typically the final cart step.

Handling Errors

• Validation errors: Missing required fields, invalid formatting, captcha, and similar validation issues are reported through standard ExpressionEngine error handling.
• Payment results: Branch on the authorized, processing, declined, and failed Boolean variables provided by submitted_order_info. Use error_message only as human-readable provider feedback; do not compare its exact wording or use it as the success/failure test.

Each checkout attempt creates an order entry. Using distinct order statuses for success/failure states is important for reporting and reconciliation. Configure these in CartThrob order settings.

It is also helpful to keep your merchant account/gateway error documentation on hand so support staff can map gateway error codes/messages to customer-facing guidance quickly.

Order Complete

Use submitted_order_info on the order-complete page to show payment outcomes and order details. Show confirmed-success messaging only when authorized is true. For offsite or asynchronous gateways, the customer can return before the gateway has confirmed payment; show a pending message when processing is true and do not treat the browser return itself as proof of payment. After confirmed checkout, it is common to display confirmation messaging, order recap details, invoice/account links, and next-step instructions.