How do I give free items (buy X, get Y free) from a metafield?

A metafield-driven deal can also give items away for free. Add entries with a free-items key to the same custom.volume_discounts list, for example [{"min_qty": 2, "discount_percent": 10}, {"min_qty": 3, "free_qty": 1}, {"min_qty": 4, "free_qty": 2}]. The quantity counts every item in the cart, free ones included: {"min_qty": 3, "free_qty": 1} means 3 items, 1 of them free: the customer puts 3 in the cart and pays for 2. Nothing is added to the cart automatically. The free items are always the cheapest ones in the cart for that product, and they are free exactly, with no rounded percentage. Above the tier, the offer repeats: with the ladder above, 7 items get 3 free (a pack of 4 plus a pack of 3) and 5 items get 2 free, with the 5th item at full price. Turn it on by entering the key you use, such as free_qty, in “Free items field name” in the deal’s Metafields section.

Steps

1. Set up a metafield-driven deal first, as described in the metafield-driven tiers guide.
2. Add free-items entries to the product’s or variant’s custom.volume_discounts list, for example {"min_qty": 3, "free_qty": 1}. “min_qty” is the total number of items, free ones included.
3. In the app, open the deal, choose Metafields in the settings rail and enter your key, for example free_qty, in “Free items field name”.
4. Choose a product that carries free entries and use “Refresh preview tiers”. A note names the product and lists the free tiers it found there, for example “3 items, 1 of them free”.
5. Save the deal, then run a test checkout with enough items to reach a free tier, ideally with two variants at different prices.