Child pages
  • Add Free Product to Cart - Magento 2
Skip to end of metadata
Go to start of metadata


Firefox user notice:

Please use a different web browser to view this document.

Sorry for the inconvenience.

Add Free Product to Cart for Magento 2 allows automatically adding discounted or free simple, configurable, and downloadable products. The promo items are added based on the rules configured in the backend. The customers are informed about active promo campaigns via customizable banners and popups. It lets merchants be sure that their campaigns will engage as many as possible customers, and the high-level dashboard will notify admins about their campaign effectiveness.

Compatibility: Magento Open Source 2.2.X, Magento Commerce 2.2.X

  Product Page

Thank you for choosing Aheadworks!

Installing Add Free Product to Cart

Command Line Installation

1. Backup your web directory and store database

2. Download the Add Free Product to Cart installation package

 3. Upload the contents of the Add Free Product to Cart installation package to your store root directory

 4. In the SSH console of your server, navigate to your store root folder:

cd path_to_the_store_root_folder


php -f bin/magento module:enable Aheadworks_Afptc


php -f bin/magento setup:upgrade


php -f bin/magento setup:static-content:deploy

5. Flush the store cache, log out from the backend, and log in again


Make sure the installation is done from under the FTP administrator account. Otherwise, make sure to set 775 permissions to the store root directory after the extension is deployed.


Composer Installation

1. Log in to your customer account at and navigate to Account -> Composer access;

2. Configure your store to work with the Aheadworks composer repository:

Add composer repository to composer.json by running:

composer config repositories.aheadworks composer in the Magento installation root.

Use a key pair provided as login and pass. You can optionally save them in the global composer auth file.

 3. You can start using AW composer now.

 For extension names, navigate to Account -> Composer access.

 4. Open the root Magento directory on your server and send Composer the following command:

composer require <component-name>:<version>

Note: Use the previously copied component name and version.

 5. Make sure that Composer finished the installation without errors. Flush store cache, log out and log into the backend again.


Getting Around

Extension Logic

The Add Free Product to Cart extension performance is based on the rules. Thus, you can create, edit and delete the module rules in the backend. The rules are based on the cart content. It means, that as soon as customers add the products which correspond to the rule conditions, shoppers will get the offer to add the promo items to the cart or these items can be added automatically, depending on the settings configured.

Backend Configuration 

Add Free Product to Cart Backend Configuration

General Settings

Configuration page of the extension (Stores > Configuration > Aheadworks Extensions > Add Free Product to Cart) includes two sections: Default Title Of Popup and Hide options of configurable products.

  • Default Title Of Popup section is filled by a store admin for displaying in case of several promo offers are active.

  • Hide options of configurable products section offers two modes for choosing.


See how it looks in the frontend.


The size and color options are expanded.


The size and color options are hidden to see them, customer should click the "configure" link.

Setting the option to "Yes" makes sense if your offers may contain both configurable and simple products.

After all sections are completed, you should click the save Config button.


General settings



Note that If the Offer Only Those Products Which Are In Stock functionality is enabled, customers will see only those products which are in stock (Qty> = 0) regardless of whether the backorder is enabled or not. It means that you are able to offer only those items which are available now.
In the case when all promo products are over (if this option is enabled), then the rule will be automatically disabled and promo banners set in the rule will disappear from the frontend.

Rule Settings

Buy X Get Y

  • First time - customers will get a promo item or an offer only the first time when the conditions of the rule are met. E.g. customer will receive a promo product only for the first product X, disregarding on how many Product X they buy;
  • Every time - customers will get a promo item or offer every time when the conditions are met. E.g. with every product X customer can get product Y
  • Every Nth time- customers will get a promo item or offer every second or every fifth time. E.g. for every 3 product X customer will get 1 product Y.


This scenario is for those merchants who want to evaluate the effectiveness of a certain channel (email, FB, Tweeter, printed media).

There are no ‘first, every, every n-th time’ option in this scenario. The coupon can be applied by the same customer unlimited number of times during the promo campaign. If you need to limit the number of uses, you should open the corresponding rule in the Cart Price Rules (created automatically upon save of the rule of the extension) and edit the options "uses per coupon" and "uses per customer".

The conditions for all products in the cart are added to the rule for the Coupon scenario. In addition to the usual and self-explanatory conditions, we have divided the Subtotal condition into 2:

  • Subtotal (including promo products) - the rule considers a complete subtotal of all the products in the cart, including promo products which are added following to the other extension rules. Please note that subtotal does not include a discount, so if there are 2 products in the cart, one of which is a free promo item, it's price still will be taken into account.
  • Subtotal (excluding promo products) - this condition considers the sum of prices multiplied by the quantity for non-promo products only. All the products added with using any rules of our extension will not be taken into account.

  • "Non-Promo Product" | Price: $30 | qty:1 | Row total: $30

  • "Promo-product 50% Off" | Price: $20 | qty: 1 | Row Total: $20

  • Subtotal: $50

  • Promo discount: -$10

  • Grand total: $40

  • Subtotal (including promo products) = $50Subtotal (excluding promo products) = $30

Popup Settings


Note that the Text in the Popup Header option will be applied only if all items in the popup are offered by the same rule. In case of multiple rules, the text from ‘Stores->Config’ will be used.

Promo Settings

  • Promo Text - the call to action message related to your promo offer;
  •  Image - the image that will be displayed near the promo items;
  • Header - the text for the promotional popup header;
  • Description - a brief description of your current promo that your customers will see if they click promo image;
  • URL - the link to the page you want to redirect your customers;
  • URL Text - a special text message for encouraging your customers to follow the offered link.



Note that the Promo Settings block is available only for the Buy X Get Y scenario.

Note that If conditions are set as excluding (cart does not contain .... ) - promo block will be displayed on all products in the store, so merchant may want either to disable promo options, or reconfigure rule so it doesn't contain negative conditions of highest level.


The dashboard displays the following info:

  • Active promo campaigns - the number of active promos;
  • Total sales - total amount of all orders with at least 1 promo item, $$;
  • N% of all sales - the percentage of total sales generated by promos;
  • Orders - total number of orders with at least 1 promo item;
  • N% of all orders- the percentage of total orders generated by promos.
  • Avg cart total of orders with promo items, $$
  • Avg cart total of all orders, $$
  • Promo Items per order - average qty of promo items per order (it calculates only orders with at least 1 promo item)
Note that when an admin selects some website in a filter settings, the dashboard displays information about that website only, in that website currency.

Rule setup examples

a) For SKU

b) For a number of products

c) Coupon (subtotal excluding promo products)


  1. Why the information about the promo is displayed in the order but invoices and credit memos contain the least of it? In Magento 2.2.6 there are no extension points in invoices and credit memos, unlike the orders. If they will be added later, we will also add the necessary information to the invoices and other documents.

  2. Why have the rules been separated from the cart price rules?
    It allowed us to bypass some pitfalls and made a more user-friendly and cleaner interface. The cart price rules already have a lot of settings, and we are sure that adding our options there would be an enormous challenge for the admin.

Product Page

Need Customization?

Magento 2 Custom Development Services by Aheadworks

You can always find the latest version of the software, full documentation, demos, screenshots, and reviews on
License agreement:
Contact Us:
Copyright © 2019 Aheadworks Co.

  • No labels