Skip to main content
Explanation

Checkout Experiment Guide

Last Updated: June 26, 2026

Table of Contents​

  1. Overview

  2. Experiment Types

  3. Hosted Fields Constraint

  4. Recommended Approaches

  5. What to Avoid

  6. Troubleshooting

  7. Related Documentation

Overview​

UltraCart provides two primary mechanisms for A/B testing checkout layout and design: element/section experiments and theme experiments. Each has different capabilities and constraints. For checkouts that use hosted payment fields, the choice of experiment type matters — using the wrong approach produces a hard error that prevents checkout from loading.

Experiment Types​

Element and Section Experiments​

An element or section experiment places both the original and variant content in the DOM simultaneously, then activates one based on the experiment assignment. This means both versions are technically present in the page source at the same time, even though only one is visible to the customer.

This approach works well for non-payment sections such as:

  • Page headers and footers

  • Product descriptions and imagery

  • Call-to-action buttons and copy

  • Layout and spacing changes that do not include form fields

Theme Experiments​

A theme experiment swaps the entire checkout theme for a variant, ensuring only one complete checkout layout is ever active at a time. Only one theme renders for any given session, so there is no risk of duplicate form elements appearing in the DOM simultaneously.

This approach is appropriate for:

  • Testing significantly different checkout layouts or designs

  • Any experiment that involves restructuring the payment section

  • Cases where the element experiment approach produces a duplicate field error

Hosted Fields Constraint​

UltraCart's checkout uses hosted fields for PCI-compliant handling of sensitive payment data (credit card number, CVV). The hosted fields system works by locating a specific input element via a jQuery selector and replacing it with a secure iframe. This process requires that exactly one element per field type exist on the page at the time of initialization.

When an element experiment includes a credit card number field in either its original or variant content, both versions are present in the DOM at the same time. The hosted fields initializer finds two matching elements and produces the following error:

There is more than one checkout credit card number element on the page. This is not supported and will cause problems.

This is not a configuration error — it is a hard architectural constraint. The hosted fields system cannot operate with two credit card inputs on the same page, regardless of which one is visible.

Option 1: Theme experiment (preferred for payment section changes)​

Use a theme experiment when your design change involves the payment section or any part of the checkout that includes hosted fields. Steps:

  1. Build the variant checkout design in a separate storefront or test environment.

  2. Submit the finished theme as a pull request from the test storefront into the production storefront.

  3. Configure the experiment to use the new theme as the variant.

This ensures only one checkout layout is ever rendered per session, keeping the hosted fields constraint satisfied.

Option 2: Element experiment on non-payment sections​

Use an element or section experiment only on portions of the checkout page that do not contain hosted field inputs. Safe targets include:

  • The page header or progress indicator

  • Order summary and item display sections

  • Shipping address and method selection (plain HTML form fields only)

  • Trust badges, copy, or layout elements above or below the payment form

Do not include the payment form block — specifically any section that renders the credit card number or CVV inputs — in either the original or variant content of an element experiment.

Option 3: Separate test storefront​

Build and validate the new checkout design on a cloned test storefront. When the design is ready, promote it to the production storefront via a theme pull request. This is the lowest-risk approach for large redesigns.

What to Avoid​

Copying an entire checkout section — including the payment block — into an experiment variant is the most common cause of the duplicate hosted field error. The issue occurs even if the section appears visually correct in the editor, because both the original and the variant are inserted into the DOM before the experiment activates one of them.

Specifically:

  • Do not copy a section that contains the credit card number or CVV input into an experiment variant on the same live checkout page.

  • Do not attempt to work around the error by hiding one of the fields with CSS. The hosted fields initializer scans the DOM regardless of visibility.

  • Do not replicate the entire checkout form across two experiment variants.

Troubleshooting​

Error: More than one checkout credit card number element on the page​

Symptoms: A popup or console error appears during checkout stating that multiple credit card number elements were detected. The checkout may fail to load or payment fields may not initialize.

Root Cause: An element or section experiment includes a credit card number input in both the original and variant content. Both versions are present in the DOM simultaneously, which violates the hosted fields single-instance requirement.

Diagnosis: Inspect the page source or DOM while the experiment is active. Search for all inputs or containers that would match your hosted fields selector (typically #creditCardNumber or a class-based selector). If more than one is found, the experiment structure is the cause.

Solution: Switch the experiment to a theme experiment, or remove the payment section from the element experiment scope so only non-payment elements are varied.

Error: Express checkout options not showing on copied storefront

Symptoms: After copying a storefront or section to a new storefront for testing, express checkout options (Link, Amazon Pay, etc.) do not appear.

Root Cause: Express checkout availability depends on item type and account-level payment method configuration. Auto-order items suppress Link and Amazon Pay. Additionally, payment method availability is scoped to the storefront — copying a theme does not copy payment gateway configuration.

Diagnosis: Confirm what item type is in the cart. Check payment method settings in the test storefront's configuration.

Solution: Verify the item is not on auto-order if Link or Amazon Pay are expected. Confirm payment methods are configured on the test storefront independently.

Was this page helpful?