I think I finally figured how the mysterious ‘free_free’ shipping module is working in zencart!

Let me start by saying that this is about the technical details, not about configuring it (although, that is part of it).

The first thing to notice is that usually when the user selects a shipping method, the following array/map is populated in the session:

$_SESSION['shipping'] = array(
'id' => 'SHIPPING_MODULE_ID',
'title' => 'METHOD_TITLE'
'cost' => 'THE_SHIPPING_COST_AMOUNT
);

However, if the checkout code detects a virtual cart cart, things look different:

$_SESSION['shipping'] = 'free_free';
$_SESSION['shipping']['title'] = 'free_free';
$_SESSION['sendto'] = false;

I am not entirely sure if this code is really intentional, because first it assigns a string value to $_SESSION['shipping']. In the second line $_SESSION['shipping'] is treated as an array to set the shipping method title (not a readable string, but an id!!).
Finally, the shipping address is cleared as there is no need for shipping of virtual goods (they typically are downloaded).

If the cart is not virtual the story continues and the code checks if the ot_shipping order total module is installed. If so, it checks if free shipping is enabled and if that is the case checks if the shipping destination (and cart total) qualify for free shipping.

Now, the following only works due to some help from the templates. The checkout_shipping template also checks for free shipping (using the same logic, in ZenMagick you can use $utils->isFreeShipping($shoppingCart)) and if so, doesn’t offer the usual selection of shipping modules, but creates a hidden field with ‘free_free‘ preselected and no further choice. So this is where the user is forced to accept free shipping.

Back to the server side: So, if the cart qualifies for free shipping and shipping was selected the selected shipping module is set in the session as explained above, with some special treatment if the selected shipping id is ‘free_free‘ (since there isn’t a shipping module with that id).

Finally, the ot_shipping module will do some special treatment if the shipping_method is ‘free_free‘.

Done!

Now all I need to do is figure out a way of doing all this without the need for all that interaction!

From looking at all the code it seems that the backend would be able to support offering free shipping together with the regular shipping methods. Instead of creating a hidden field all shipping methods could be displayed as usual and then a hardcoded! free shipping option with the shipping id ‘free_free‘.
In addition a flag/setting could be created to control whether free shipping should be enforced or not to get pretty much the same behaviour as now.

In the long run it would be much nicer to have a dedicated shipping module for this and then just just that to control all aspects of free shipping (well, this kind of free shipping…)