Documentation You are here: start » v » 2.0 » snippets » checkout_upsells

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
v:2.0:snippets:checkout_upsells [2016/08/17 11:42] – adamv:2.0:snippets:checkout_upsells [2025/05/30 21:44] (current) – foxybrett
Line 2: Line 2:
  
 Beginning in version 2.0 we've added some basic upsell functionality into the checkout. It allows you to quickly show a modal window to customers on the checkout providing opportunities for them to add additional products to their cart prior to checkout. Beginning in version 2.0 we've added some basic upsell functionality into the checkout. It allows you to quickly show a modal window to customers on the checkout providing opportunities for them to add additional products to their cart prior to checkout.
 +
 +<wrap tip>It also works on subscription cancellations!</wrap> If you want to display a message before a customer cancels their subscription, this functionality can handle that as well. (Sample code at the bottom of the page.)
  
 The upsell modal window is displayed on page load of the checkout, based on conditions you set within your custom Twig logic. The upsell modal window is displayed on page load of the checkout, based on conditions you set within your custom Twig logic.
 +
 +{{:v:2.0:snippets:foxy_checkout_upsells.png?nolink&500|}}
 +
  
 ===== Step 1: Add custom Twig to your checkout ===== ===== Step 1: Add custom Twig to your checkout =====
Line 28: Line 33:
 Inside this block tag you'll place your own custom logic and HTML. The most common use case is that of offering an link or form to add an extra product into the customers cart, unless they already have the product in their cart. That approach could look simply like this: Inside this block tag you'll place your own custom logic and HTML. The most common use case is that of offering an link or form to add an extra product into the customers cart, unless they already have the product in their cart. That approach could look simply like this:
  
-<code>+<code html>
 {% block upsell_modal %} {% block upsell_modal %}
-    {% set hasUpsell = false %}+    {% set showUpsell = true %}
     {% for item in items %}     {% for item in items %}
         {% if item.code == "my-upsell" %}         {% if item.code == "my-upsell" %}
-            {% set hasUpsell = true %}+            {% set showUpsell = false %}
         {% endif %}         {% endif %}
     {% endfor %}     {% endfor %}
-    {% if not hasUpsell %}+    {% if showUpsell %}
         <h2>Special offer just for you!</h2>         <h2>Special offer just for you!</h2>
         <p>As a limited time offer, we're offering you this unique product for only $12.95. That's $5 off our normal price!</p>         <p>As a limited time offer, we're offering you this unique product for only $12.95. That's $5 off our normal price!</p>
-        <p><a href='https://{{ config.store_domain }}/cart?name=Upsell+Product&code=my-upsell&price=12.95'>Yes, please add this product to my cart!</a> | <a data-modal-action="cancel">No thanks</a></p>+        <p><a href='https://{{ config.store_domain }}/cart?name=Upsell+Product&code=my-upsell&price=12.95'>Yes, please add this product to my cart!</a> | <a data-remodal-action="cancel">No thanks</a></p>
     {% endif %}     {% endif %}
 {% endblock %} {% endblock %}
Line 45: Line 50:
  
 A few things happens within this code. A few things happens within this code.
-  - Firstly, we set a variable called ''hasUpsell'' to false +  - Firstly, we set a variable called ''showUpsell'' to true 
-  - Next, we loop through the items in the cart and look for any products with a code of ''my-upsell''. If one is present, we set the ''hasUpsell'' variable to false. +  - Next, we loop through the items in the cart and look for any products with a code of ''my-upsell''. If one is present, we set the ''showUpsell'' variable to false. 
-  - Finally, if ''hasUpsell'' is still false, meaning the customer hasn't previously purchased the upsell - we display some HTML tempting the customer to our upsell product. If they have, and ''hasUpsell'' is true - we don't output any HTML, leaving the block empty and so the modal won't display at all.+  - Finally, if ''showUpsell'' is still true, meaning the customer hasn't previously purchased the upsell - we display some HTML tempting the customer to our upsell product. If they have, and ''showUpsell'' is false - we don't output any HTML, leaving the block empty and so the modal won't display at all. 
 + 
 +==== Important Notes ==== 
 + 
 +  * If your store has link and form encryption enabled, any add to carts you include within the modal will also need to be encrypted. [[v:2.0:hmac_validation|Review the wiki page for the link/form encryption]] for details on doing that. 
 +  * Any images that you include within your markup need to be served securely. If you're not already using a remote custom template that you're caching, you can have the image cached manually as [[v:2.0:templates:intermediate-automagicache#caching_assets_manually|detailed here]].
  
 ===== Step 2: Enable Upsells ===== ===== Step 2: Enable Upsells =====
Line 66: Line 76:
  
 If you set ''enabled'' to ''false'' in this code - it will disable the upsell functionality from operating on your cart. Alternatively you can also simply remove the above code from the custom values textarea and save your configuration to turn off the upsell functionality. If you set ''enabled'' to ''false'' in this code - it will disable the upsell functionality from operating on your cart. Alternatively you can also simply remove the above code from the custom values textarea and save your configuration to turn off the upsell functionality.
 +
 +===== Step 3: Taking it further =====
 +
 +You have complete control over what logic the Twig includes, and what HTML is output within the modal window. As with any FoxyCart templates, you can also include any custom styles you need - meaning you can create very complex and beautiful upsell displays for your store.
 +
 +Some examples of more advanced set ups you could take:
 +
 +  * Use a custom session attribute to track if a customer has already added or declined an upsell product. This could be done by sending a [[v:2.0:json|JSONP request]] off to the cart on the dismiss link being clicked, and by including the custom attribute in the add to cart. You could then check for that custom attribute in your twig logic to prevent the modal from showing again.
 +  * On page load of the checkout, you could send off a [[v:2.0:json|JSONP request]] setting a custom session attribute of the current date/time. You could then check against that variable when deciding whether to show the upsell or not, and include a countdown timer within the modal showing how much longer the offer would be valid for.
 +  * If you wanted to also trigger the upsell modal off of other events on the checkout - such as removing a product from their cart or clicking a button or link - it can be shown by calling ''FC.checkout.showUpsellModal()''. This function will re-render the upsell block and display if it's enabled and has at least one HTML element within the block to display.
 +
 +==== Only showing the upsell window once across customer sessions ====
 +
 +If you want to ensure the customer only sees the upsell modal once across multiple different checkout attempts, you can utilise cookies to store details about the customer that can be retrieved in future checkout sessions. As an example, the following code will add a cookie that will last for 30 days if the customer either closes the upsell modal or submits the add to cart form, preventing the customer from seeing it again for that timeframe. 
 +
 +You would include this code in the "footer" textarea of the "Add custom header and footer code to the templates" option found on the "configuration" page of your stores administration:
 +
 +<code javascript>
 +{% if context == "checkout" %}
 +<script>
 +    var upsell_cookie_name = "fc_completed_upsell",
 +        cookie_expires_in = 30; // default, in days
 + 
 +    $(function() {
 +        var has_upsell_cookie = document.cookie.split(';').filter(function(item) {
 +                return item.indexOf(upsell_cookie_name + '=') >= 0
 +            }).length;
 +        if (has_upsell_cookie) {
 +            $('[data-fc-id="block-upsell-modal"]').html("");
 +            if (FC.checkout.upsell_modal) {
 +                FC.checkout.upsell_modal.close();
 +            }
 +        }
 + 
 +        // On closing the modal
 +        $('body').on("mousedown", '[data-fc-id="block-upsell-modal"] [data-remodal-action="cancel"]', function() { addUpsellCookie(); });
 +        // On submitting a form in the modal
 +        $('body').on("submit", '[data-fc-id="block-upsell-modal"] form', function() { addUpsellCookie(); });
 +    });
 + 
 +    function addUpsellCookie(days) {
 +        var expires = "",
 +            date = new Date(),
 +            days = parseInt(days);
 +        
 +        if (typeof days !== "number" || !isFinite(days) || Math.floor(days) !== days) {
 +            days = cookie_expires_in;
 +        }
 +
 +        date.setTime(date.getTime() + (days*24*60*60*1000));
 +        expires = "; expires=" + date.toUTCString();
 +        document.cookie = upsell_cookie_name + "=true" + expires + "; path=/";
 +    }
 +</script>
 +{% endif %}
 +</code>
 +
 +You can modify this script as needed, updating the ''cookie_expires_in'' variable to change the number of days they shouldn't see the upsell for. 
 +
 +The script also supports passing a custom cookie length, in days, to the ''addUpsellCookie()'' function, so you could customise the number of days the customer shouldn't see the upsell modal for depending on what they interact with. If no parameter is passed, then the default value is used from the top of the script (30 days in the example code above). For example, if you wanted to just hide the modal if cancelled for the default amount, but hide for a year if the customer submits the form - you could edit the form submission event hook like this:
 +
 +<code javascript>    $('body').on("submit", '[data-fc-id="block-upsell-modal"] form', function() { addUpsellCookie(365); });</code>
 +
 +Finally, you can also comment out either of the event hooks that are triggered on closing the modal or submitting a form, depending on your needs. For example if you only wanted to prevent the upsell from showing again if the customer submits the form, you would comment out this line like this:
 +
 +<code javascript>
 +    // $('body').on("mousedown", '[data-fc-id="block-upsell-modal"] [data-remodal-action="cancel"]', function() { addUpsellCookie(); });
 +</code>
 +
 +
 +
 +===== Displaying a Subscription Cancellation Upsell or Message =====
 +
 +All the steps above should be followed, but here's code tailored to display the message based on the ''is_subscription_cancel'' value. This will //only// display when a customer uses a subscription cancellation link:
 +
 +<code html>
 +{% block upsell_modal %}
 +    {% if is_subscription_cancel %}
 +    <div id="cancelConfirmModal">
 +        <h2>Hi there! Before You Cancel...</h2>
 +        <p>We understand things change, but if you're cancelling because:</p>
 +        <ul>
 +            <li>You're not getting the value you expected?</li>
 +            <li>Encountering technical difficulties?</li>
 +            <li>Finding it complex to use?</li>
 +            <li>Have questions about your plan or billing?</li>
 +        </ul>
 +        <p>We're here to help you get the most out of our service! And we're happy to help.</p>
 +        <div>
 +            <ul>
 +            <li>
 +                <a href="mailto:hello@example.com">✉️ Email Support or Schedule a Call</a>
 +            </li>
 +            <li>
 +                <a data-remodal-action="cancel">No Thanks, Continue to Cancel…</a>
 +            </li>
 +            </ul>
 +        </div>
 +    </div>
 +    {% endif %}
 +{% endblock %}
 +</code>

Page Tools

Site Tools