Solution
The main idea of the solution was to reuse the existing Addon extras feature and make something not tied only to the Ketchup idea. Our solution will able to the client offer any item to the user.
We also use the Addon Extras feature in the Bag With Handles solution. The Addon extras feature will solve for us the following:
A modal that will hold all the extras items
The edit of the extra item
The re-order behavior (not letting the client open a re-order with an extra added directly)
All the flow for the order, receipt, and so on, is already done
Requirements to work
For this solution to work, we need to ensure that Sanity is properly configured:
The creation of the desired Add On Section
The sections here can be created and saved to be used later because they need to be added to the feature menu.
Add the Add On Sections that we want to show in the cart into Feature Menu
The order of the list defines the order that the sections will be shown on the cart checkout page.
Configure the Add On Section correctly to have the behavior to deal with free items:
“Show as a separate section on cart” (ON)
“Make options in this section as free add-ons” (ON)
“Service Modes”
Here we’ll choose the desirable service modes that we want to offer the promotion
Configure the options (addons) for this Add On Section
Add the paid item (“Option”)
Add the free item (“Free Option”)
Important: the free item needs a PLU with zero price to have the correct behavior
In the “Vendor Configs”
“PLU Type” = “Constantplu”
“Constant PLU” field = “zero PLU”
Obs: for development, we can use the “PLU Type” as ignore, and the product will have zero as the value
Configure the “Menu options that Offer the Free Options Above”
Here we’ll configure the item that will receive the offer and the maximum free items quantity
Configure the “Free Add On Modal” fieldset if wants to show the promotional modal when the user enters the checkout page
“Show Free Add-On Modal at Checkout” → if ON we’ll have this modal shown in the cart
The image and description are optional. Title and CTA are required if the toggle is ON.
To avoid quantity limits for the added items in the cart we need to configure the following on Sanity:
In the example above the user can select only 20 items (individually) in the cart.
This limit will also affect the addons items. Even if we offer 30 free items the user cannot select more than 20 items (in this example).
Front-end behaviors and Business rules
After all the requirements are configured, we’ll have the following things on the FE UI:
Promotional modal when entering the checkout the first time/journey/order
Basic Rules
Show the modal only for the first time (and always if we have a “new cart”, cleaning the cart and adding the products again)
If the user hits F5 the modals already saw will not be shown on the screen, only the new ones
If we have only one modal ON we’ll not show the carousel
For more details of carousel buttons behavior: https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4169040346/Whitelabel+Add+free+extras+modal+on+checkout+page+cart#Task-2%3A-Add-carousel-logic-in-modal-content
The modal will show content for every section that has a matching item with an offer on the cart
Checkout sections
In this example, I have the “Add Ketchup” and “Add Sauces” sections. Some rules for this part of the screen
If the user did not add the free items through the promotional modal he’ll see the free offers on the screen
If click on the free item:
Is the maximum of free items selected in the cart?
Yes - show the paid item in the section
No - hide the section from the screen if the section doens’t have other items to offer
We’ll only show the section if at least one item from the section has an offer
We’ll show only items that have an offer in the section (individually)
Your Cart behavior with free/paid items
The free item will have a description about the maximum of the free items available with the items combined in the cart:
Quantity of the item that offers the free item X sanity free quantity → In this example “The Sandwich” offers 1 free item, so: 1 x 1 = the maximum for Ketchup free is 1
The free item will have 0.00 for the price (will not use any label here because we want to ensure the same consistency between receipt and front-end)
Automatic “balance” of the cart content based on the following rules:
The user cannot pay for an item if he has free items available to select
The user cannot buy additional free items (besides what's been offered)
The app will remove/add free and paid as needed to balance the original quantity on the cart
Remove free and paid items from the cart if the main item (that holds the offer) is removed
Extras modal to edit addons
The user will edit the quantity for the addons by clicking on the “Edit” button that will open the “Add extras” modal
The modal will also respect the rules for maximum free items → In this example the user can select a maximum of 1 Free item and he’ll be able to select the paid item if want more add-ons
The paid item will only be offered if the free is on maximum during the edition in this modal
The edition in this modal doens’t changes the cart in the background. The edition will be made only after clicking on the “Update Order” button
Troubleshoot
Section with free items is not in the checkout?
All the flags and toggles should be ON as showed in the Requirements section
Sanity needs to be configured properly and the right item (that is offering the free ones) needs to be in the cart
If some item used as a free/paid addon in the Add On Section options has an invalid configuration the entire section will be invalid (for example an invalid PLU, or invalid item config, which will be checked on POS)