Migrating customizations to Fluid Checkout Lite 4.0+

Last update: December 10th, 2024

Update: Included information about compatibility with plugins Delivery & Pickup Date Time for WooCommerce by CodeRockz (free and PRO) moved to the Fluid Checkout PRO, and how to get the legacy plugin with this compatibility for current users for a limited time.

Fluid Checkout Lite 4.0 will be released soon with important changes that might impact your website if you have made customizations to our plugins or added code snippets to change how our plugin works.

If your website does not have any customizations or code snippets, it should work in the same way as before updating it to these newer versions.

The information contained in this customizations migration guide is meant for Developers and customers who are comfortable with editing PHP code. If that is not you, jump to the section “Will these changes affect my website?” or forward this guide to your developer to check it for you.

In short:

  • These changes only affect websites that have added customizations for our plugins;
  • Along with Fluid Checkout Lite 4.0+, we will also release updates for the PRO plugin and other add-ons;
  • When using custom sub-steps, they will need to be registered using the new appropriate functions;
  • Some filter hooks have changed names and parameters;
  • Some template files have changed and might need to be updated.

All you need to know to be prepared for these changes:

We will update this guide when the new versions of the plugins are released with these changes or whenever necessary.

Get our product updates in your inbox

You will receive release notes and information about how to get the most out of our plugins.

Product updates - FC

We don’t spam! Read our privacy policy for more info.

Will these changes affect my website?

Your website will only be affected by these changes if you have customizations added to it, and if these customization are related to the parts of the plugin that changed.

These changes will NOT affect your website if:

  • Your website does have not added any customizations for Fluid Checkout or any of the add-ons;
  • Your website does not use any code snippets related to Fluid Checkout or any of the add-ons;
  • Your website does not have any customizations for the template file cart/cart-items.php.

The information contained in this customizations migration guide is meant for Developers and customers who are comfortable with editing PHP code. If you are still unsure if these changes will affect your website, please forward this guide to your developer to check it for you.

Why are these changes necessary?

We try as much as possible to avoid making changes that could break websites using Fluid Checkout or any customizations made to it, but sometimes these changes are necessary. If you are using Fluid Checkout without customizations made in code, these changes will not likely affect your website as explained in the section “Will these changes affect my website?” above.

Previously to Fluid Checkout Lite 4.0+, sub-step sections were directly displayed to the step sections. This limited how Fluid Checkout could work with and manipulate the sub-step sections.

We decided that it was time to overcome this limitation and prepare Fluid Checkout for adding new features in the future, such as the much requested Order Pay page optimization feature coming to Fluid Checkout PRO soon after these new versions are released.

Which plugins and add-ons are being updated with these changes?

Along with Fluid Checkout Lite 4.0+, the following add-ons will also be updated with these changes:

  • Fluid Checkout Lite 4.0+
  • Fluid Checkout PRO 3.0+
  • Address Book 3.0+
  • EU-VAT Assistant 2.0+

My website has customizations, how can I know if my website will be affected?

The best way would be to test the upcoming update directly in a test/staging copy of your website. If you have a test/staging copy of your website, you can use the beta version from the link below:

For customers with a valid license key for Fluid Checkout PRO or any of the add-ons, if you need to update your customizations, please open a support ticket requesting the beta versions for these plugins:

  • PRO: upon request
  • Address Book: upon request
  • EU-VAT Assistant: upon request

If you encounter any issue while using this beta version, please open a support ticket and we will work to fix these issues before releasing the official update.

Otherwise, you can also search through the code of your website and look for any reference to the parts that have changed. These are the places that customizations are most likely added:

  • In the file functions.php in your theme or child theme;
  • Code snippets added using plugins such as Code Snippets;
  • Custom plugins created specifically for your website.

Search for any references to:

  • output_substep_start_tag
  • output_substep_end_tag
  • fc_is_step_complete_billing_field_keys_skip_list
  • fc_output_step_ which target any references to any step sections, such as fc_output_step_shipping or fc_output_step_billing and others steps.

And if you are using Fluid Checkout PRO, also search for references to:

  • Template file cart/cart-items.php

If you encounter any reference to the changed parts above, your website will likely be affected. In that case, continue reading this guide and make the necessary changes as explained.

If you are still not sure whether your website will be affected and need help with this, please open a support ticket.

Making your customizations compatible with the upcoming changes

These are the changes that will likely require changes to your customizations to be compatible with the upcoming updates:

Fluid Checkout Lite 4.0+

Fluid Checkout PRO 3.0+

Sub-step sections now need to be registered

Previously to this version, sub-step sections were displayed by directly outputting the sub-step sections inside the step sections using action hooks such as fc_output_step_shipping or fc_output_step_billing.

Since Fluid Checkout Lite version 4.0+, sub-step sections need to be registered similarly to how step sections are registered.

When registering a new sub-step section, please note that:

  • You can only do it after the default steps and sub-steps have already been registered which happens at the action hook wp priority 10;
  • You need to provide the values for the step id, sub-step id, sub-step title, a function to render the sub-step fields, and a function to render the sub-step review text;
  • Optionally, you can also provide a function to determine if the sub-step should be considered complete, otherwise it will always be considered complete; and
  • Optionally, you can provide a list of HTML attributes to be added to the sub-step section start tag.

See complete example below:

/**
 * Output checkout fields for the custom substep.
 *
 * @param  string  $step_id     Id of the step in which the substep will be rendered.
 * @param  string  $substep_id  Id of the substep.
 */
function fluidcheckout_output_custom_substep_fields( $step_id, $substep_id ) {
	// Code to output your custom sub-step checkout fields
	echo 'FIELDS';
}

/**
 * Output the substep review text for the custom substep.
 * 
 * @param  string  $step_id     Id of the step in which the substep will be rendered.
 * @param  string  $substep_id  Id of the substep.
 */
function fluidcheckout_output_custom_substep_review_text( $step_id, $substep_id ) {
	// Code to output your custom sub-step review text, displayed when the step is completed.
	echo 'REVIEW TEXT';
}

/**
 * Determines if custom substep should be considered complete.
 *
 * @return  boolean  `true` if the substep is complete, `false` otherwise.
 */
function fluidcheckout_is_custom_substep_complete() {
	// Checks for any criteria that would indicate the substep is not complete.
	// Return boolean value indicating if the substep is complete
	return true;
}



/**
 * Maybe register substeps
 */ 
function fluidcheckout_register_custom_substeps() {
	// Define variables
	$step_id = 'shipping';

	// Register custom substep
	FluidCheckout_Steps::instance()->register_checkout_substep( $step_id, array(
		'substep_id' => 'your_substep_id',
		'substep_title' => __( 'Custom substep title', 'your-text-domain' ),
		'priority' => 20,
		'render_fields_callback' => 'fluidcheckout_output_custom_substep_fields',
		'render_review_text_callback' => 'fluidcheckout_output_custom_substep_review_text',
		'is_complete_callback' => 'fluidcheckout_is_custom_substep_complete', // Optional, defaults to `true`
		'additional_attributes' => array(), // Optional, array of additional attributes to add to the substep container start tag.
	) );
}
add_action( 'wp', 'fluidcheckout_register_custom_substeps', 500 );

Change sub-step section titles

If you had customized the title for any existing sub-step section, these changes will probably not be affected and you can still use the filter hooks fc_substep_title_{$substep_id}, replacing {$substep_id} with the actual sub-step id.

For more information on this visit the documentation article Customize checkout steps.

Fix usage of functions output_substep_start_tag and output_substep_end_tag

The parameter $substep_title previously passed into the functions output_substep_start_tag and output_substep_end_tag has been removed as it became obsolete.

Since sub-step sections now need to be registered, you will likely not need to use these functions. But in case you still need to use these functions directly, you will have to adapt your code to remove the $substep_title parameters when calling them.

Example of calling these functions with the updated version:

// Define variables
$step_id = 'shipping';
$substep_id = 'shipping_method';
$additional_attributes = array( 'class' => 'substep' );
$output_edit_buttons = true;

// Output start tags for the substep section
FluidCheckout_Steps::instance()->output_substep_start_tag( $step_id, $substep_id, $additional_attributes );

do_something_else();

// Output end tags for the substep section
FluidCheckout_Steps::instance()->output_substep_end_tag( $step_id, $substep_id, $output_edit_buttons );

Fix usage of filter hook fc_is_step_complete_billing_field_keys_skip_list

The filter fc_is_step_complete_billing_field_keys_skip_list has been renamed to fc_is_substep_complete_billing_address_field_keys_skip_list because it is only related to the billing address sub-step and not the entire billing step.

Simply changing the name of the filter hook will fix its usage.

Use functions is_feature_enabled to check whether features are enabled

Previously to Fluid Checkout 4.0+, when checking if a specific feature is enabled or not you would have to get the option values directly and check whether the selected value matches a specific criteria.

To simplify this process, most feature classes from Fluid Checkout now provide the function is_feature_enabled which returns a true/false value and applies any specific criteria to determine if the feature is currently enabled. These functions are available on Fluid Checkout Lite, PRO and all the add-ons.

Example: check if the feature to hide optional fields is enabled:

// Check whether the feature is enabled
if ( class_exists( 'FluidCheckout_CheckoutHideOptionalFields' ) && method_exists( 'FluidCheckout_CheckoutHideOptionalFields', 'is_feature_enabled' ) && FluidCheckout_CheckoutHideOptionalFields::is_feature_enabled() ) {
	// DO SOMETHING
}

Example: check if the feature to edit cart items at checkout is enabled:

// Check whether the feature is enabled
if ( class_exists( 'FluidCheckout_PRO_CheckoutEditCart' ) && method_exists( 'FluidCheckout_PRO_CheckoutEditCart', 'is_feature_enabled' ) && FluidCheckout_PRO_CheckoutEditCart::is_feature_enabled() ) {
	// DO SOMETHING
}

Fix cart items table has been moved from cart/cart-items.php to a separate template file

The cart items table displayed from the template file cart/cart-items.php has been moved to a new and separate template file cart/cart-items-table.php. This change gives us the ability to update the cart items table separately from the enclosing section on the cart page, which is necessary for compatibility with some 3rd-party plugins.

If you have customized the template file cart/cart-items.php from our plugin, you will have to update your copy with the new changes. Most likely you would have customized the cart items table within that template file, so you may or may not need to create a copy of the template file cart/cart-items-table.php on your child theme.

Follow the steps below to update your copies of these template files:

cart/cart-items.php

  1. Open both the original template file from fluid-checkout-pro/templates/fc-pro/cart/cart/cart-items.php and your copy of that template file from your child theme;
  2. Compare the two files line-by-line and make the necessary adjustments on your copy of that template file;
  3. Save your template file to your child theme templates folder at your-child-theme/woocommerce/cart/cart-items.php;

cart/cart-items-table.php

  1. Open the original template file from fluid-checkout-pro/templates/fc-pro/cart/cart/cart-items-table.php;
  2. Create a copy of that template file to your child theme templates folder at your-child-theme/woocommerce/cart/cart-items-table.php;
  3. Make the necessary adjustments with your customizations to your copy of that template file;
  4. Save your copy of the template file to your child theme.

Make sure to test the cart page again after updating your template files to ensure that your customizations are applying. If needed, clear the template files cache from WP Admin > WooCommerce > Status > Tools to ensure the new updated template files are being used instead of that saved to cache.

Fix filter hooks for compatibility with the plugin Checkout Field Editor PRO by Themehigh

Fix usage of filter hook fc_pro_thwcfe_{$substep_id}_substep_title

The filter hook fc_pro_thwcfe_{$substep_id}_substep_title has been removed. If you had customized the title for any custom sub-step section created with this plugin, you can now use the filter hooks fc_substep_title_{$substep_id}, replacing {$substep_id} with the actual sub-step id.

For more information on this visit the documentation article Customize checkout steps.

Fix usage of filter hook fc_pro_thwcfe_custom_section_substep_hooks

The filter hook fc_pro_thwcfe_custom_section_substep_hooks was used to allow developers to change the arguments used to define in which position to display the customer sections. This filter has been renamed to fc_pro_thwcfe_custom_section_substep_position_args and expects a different data structure.

Previously this hook expected the following data structure:

// Define substep hook and priority for each position
$section_step_hooks = array(
	'position_id' => array(
		'hook' => 'hook_name',
		'callback' => 'callable_function',
		'priority' => $priority_value
	),
);

The correct and expected data structure for the new hook is now the following:

// Define substep position args
$substep_position_args = array(
	'position_id' => array(
		'step_id' => $step_id,
		'priority' => $priority_value
	),
);

If you were using this filter hook previously to updating Fluid Checkout PRO to version 3.0+, you will need to change to use the new filter name and structure for your customizations to continue to apply.

Applying changes to your customizations

If need to make any changes to your customizations, you will have to apply these changes at the same time as when updating the plugins and add-ons to these newer versions.

Ideally, you would update the plugins and make these changes first on a test/staging copy of your website so that your live/production site is not affected in case any problem happens.

Need support?

While we cannot fix the customizations on your website for you as per our support scope, we can certainly help you with any questions you may have regarding these changes.

If you encounter any issue while updating to these new versions of our plugins, please open a support ticket and we will do what we can to ensure a smooth transition.

Compatibility with plugins Delivery & Pickup Date Time for WooCommerce (free and PRO) by CodeRockz moved to the Fluid Checkout PRO

Why is this compatibility being removed from Lite?

With Fluid Checkout Lite 4.0+, we removed the compatibility and support for the integration with the plugins Delivery & Pickup Date Time for WooCommerce (free and PRO) by CodeRockz as part of the free plugin offer. The integration with these plugins will continue to be fully supported with Fluid Checkout PRO.

While it is unusual to have compatibility be removed, this integration in particular demands a much higher level of maintenance compared to other integrations and compatibility available with Fluid Checkout Lite, and we unfortunately unable to devote so much time for this as part of our free plugin.

With this change, compatibility with all plugins that offer the features for Delivery Date will only be available with Fluid Checkout PRO, as already mentioned on our homepage in the list of compatibilities available: Integration with supported order delivery date plugins (PRO).

When one of the CodeRockz plugins is detected and neither Fluid Checkout PRO 3.0+ or the Legacy Integrations plugin is also detected, an admin notice will be shown:

Admin notice telling CodeRockz Delivery Date plugins have been detected, and PRO or the legacy integrations plugin is needed.

Will I lose this compatibility after updating to Fluid Checkout Lite 4.0+?

No, and Yes.

If you already have Fluid Checkout PRO, you are covered. You will only need to also update Fluid Checkout PRO to version 3.0+ and everything should be as it was before.

Otherwise, if you are using only Fluid Checkout Lite, you can keep using the existing integration indefinitely by installing the Legacy Feature plugin we are making available for a limited time (see below). However, we recommend you upgrade to Fluid Checkout PRO to continue getting support and updates for this integration after the grace period is elapsed.

Upgrade to PRO

Installing the legacy integrations plugin to keep using the moved integrations

Fluid Checkout for WooCommerce – Legacy Integrations

The plugin is ready for use on Live sites. Although, as with any new plugins and updates, you should test it on a Staging/Test site before making changes to the Live site.

  1. Download the extra plugin Fluid Checkout for WooCommerce – Legacy Integrations and install it on your website.
  2. You will not see any changes to functionality or settings yet.
  3. An admin notice will be displayed telling you that Fluid Checkout Lite 4.0+ is needed for Fluid Checkout for WooCommerce – Legacy Integrations.
  4. Once Fluid Checkout Lite is updated to version 4.0+ or greater, the legacy integrations will keep working smoothly.
  5. The admin notice will be removed and the plugins list should look like this:
    Fluid Checkout plugins on the plugin list after update to version 4.0
  6. That is all 🙂
Download Legacy Integrations

Access to download the legacy integrations plugin will end on February 20th, 2025

Fluid Checkout PRO vs the Legacy Integrations plugin

What happens when I upgrade to Fluid Checkout PRO?

Once you install and activate Fluid Checkout PRO on your website, the plugin Fluid Checkout Legacy Integrations will be disabled automatically, and an admin notice will appear telling you that you can deactivate and delete the extra plugin:

Admin notice telling the Legacy Integrations plugin can be deactivated and deleted.