How to Add and Manage Custom Fields on the FluentCart Checkout Page

If you run an eCommerce store, you might often need to collect extra information from your customers during checkout. Most eCommerce plugins — including FluentCart — already let you capture essential details such as billing and shipping addresses, company name, or VAT ID.

However, depending on your business requirements, you might need to add custom checkout fields to collect additional data — such as delivery instructions, gift messages, or account preferences.

In this tutorial, you’ll learn how to:

• Add a custom field before the payment section using a FluentCart hook
• Validate the field data before order submission
• Save the field data into the database
• Display the custom information in the customer details page

Step 1: Add a Custom Field Before the Payment Section

FluentCart provides several action hooks that allow developers to inject custom HTML or fields within the checkout form.

To insert a field before the payment section, use the fluentcart/checkout/before_payment_fields action:

add_action('fluent_cart/before_payment_methods', function($args) {
    $termsText = 'Yes, I\'d like to receive emails with exclusive offers and updates.';

    ?>
    
    <div class="fct_checkout_marketing_opt_in" role="group" aria-labelledby="marketing_opt_in_label">
        <label for="marketing_opt_in" class="fct_input_label fct_input_label_checkbox">
            <input
                data-fluent-cart-marketing-opt-in="yes"
                type="checkbox"
                class="fct-input fct-input-checkbox"
                id="marketing_opt_in"
                name="marketing_opt_in"
                value="yes"
                aria-label="<?php echo esc_attr($termsText); ?>"
            >

            <?php echo wp_kses_post($termsText); ?>
        </label>
    </div>

    <?php
   
}, 10, 1);

This will display a checkbox before the payment fields

You can replace the field with any field, kindly note that the name attribute marketing_note or anything you provide as name attribute will be used as reference to this field during validation.

Step 2: Validate the Field Data

You can easily validate checkout inputs using the fluent_cart/checkout/validate_data filter.
Let’s make sure our custom field’s value isn’t empty so that it becomes a required field

add_filter('fluent_cart/checkout/validate_data', function($errors, $args){
    if(empty($args['data']['marketing_opt_in'])){
        $errors['marketing_opt_in']['required'] = __('Marketing Opt-in is required', 'fluent-cart');
    }

    return $errors;
}, 10, 2);

The validation message will appear in the top right corner of the page along with other validation error

Step 3: Save the Custom Field Data to Database

After a successful checkout, use the fluent_cart/checkout/prepare_other_data action to save the field value as customer metadata.

add_action('fluent_cart/checkout/prepare_other_data', function($args){
    $customer = $args['order']->customer;
    $data = $args['validated_data']['marketing_opt_in'];
    $customer->updateMeta('marketing_opt_in', $data);
}, 10, 1); 

Step 4: Display the Custom Field in Customer Details

To show the field on the customer profile page, use the hook fluent_cart/widgets/single_customer

use \FluentCart\App\Models\Customer;
add_filter('fluent_cart/widgets/customer', function ($widgets, $data) {
    
    $customerId = $data['customer_id'];
    
    $customer = Customer::query()->find($customerId);

    $marketingOptInStatus = $customer->getMeta('marketing_opt_in');

    $termsText = __('Yes, I\'d like to receive emails with exclusive offers and updates.', 'fluent-cart');

    $isChecked = $marketingOptInStatus === 'yes';

    $content = sprintf(
        '<div style="border:1px solid #e5e7eb;border-radius:8px;padding:12px;background:#fff;margin-top:8px;">
            <div style="font-weight:600;margin-bottom:4px;">%s</div>
            <div class="fct_checkout_marketing_opt_in" role="group" aria-labelledby="marketing_opt_in_label">
                <label for="marketing_opt_in_profile" class="fct_input_label fct_input_label_checkbox">
                    <input
                        data-fluent-cart-marketing-opt-in="yes"
                        type="checkbox"
                        class="fct-input fct-input-checkbox"
                        id="marketing_opt_in_profile"
                        name="marketing_opt_in"
                        value="yes"
                        %s
                        disabled
                        aria-label="%s"
                    >
                    %s
                </label>
            </div>
        </div>',
        esc_html__('Marketing Opt‑in', 'fluent-cart'),
        $isChecked ? 'checked' : '',
        esc_attr($termsText),
        wp_kses_post($termsText)
    );

    $widgets[] = [
        'title'     => __('Marketing Opt‑in', 'fluent-cart'),
        'sub_title' => __('From Customer Meta', 'fluent-cart'),
        'type'      => 'html',
        'content'   => $content
    ];

    return $widgets;
}, 10, 2);

Conclusion

Adding custom fields to the FluentCart checkout page is straightforward and highly flexible.
With just a few hooks, you can collect, validate, and display extra customer information without touching core files.