> ## Documentation Index
> Fetch the complete documentation index at: https://aiodapp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Free Gift with Purchase

> Template for auto-adding gifts, letting customers choose gifts, unlocking gifts with a discount code, or requiring a code before the customer chooses a gift.

Use **Free Gift with Purchase** when a merchant wants to offer gift products after the customer qualifies.

The template card says: "Auto-add or choose free gifts when conditions are met." The example shown in AIOD is "Buy 2 shirts, get 1 cap free."

## When to use this template

Use this template for:

* Buy qualifying items and get a free gift.
* Spend a qualifying amount and get a free gift.
* Let customers choose from available gifts.
* Auto-add a gift when the cart qualifies.
* Unlock a gift with a discount code.
* Require customers to enter a valid discount code before they can choose a gift from the widget.
* Offer a gift at a special discounted price instead of fully free.

Use another template for direct item discounts, BOGO pricing, volume tiers, shipping discounts, or multi-discount bundles.

## Entry point

In Shopify admin, open **Apps** > **AIOD Discount & Gift** > **Discount Templates**.

Click **Create** on the **Free Gift with Purchase** card. AIOD opens a form titled **Free Gift**.

## Form layout

The **Free Gift** form has three tabs:

* **Offer**
* **Advance settings**
* **Widget design**

It also includes **Switch to legacy template** and a top-right status dropdown.

## Status mode

The top-right status dropdown controls who can use or see the offer.

| Status       | Meaning                                                                             |
| ------------ | ----------------------------------------------------------------------------------- |
| **Live**     | The offer is active for customers.                                                  |
| **Testing**  | The offer is visible to the merchant for testing, but it is not live for customers. |
| **Deactive** | The offer is turned off.                                                            |

## Theme extension requirement

AIOD can show this warning: **Required: Theme Extension Should Be Enabled**.

The warning says the **Activate theme extension** button automatically enables the **Latest Widget Manager** extension. The merchant must click **Save** in the theme editor after activation.

Use this section when a merchant asks why the gift widget is not appearing on the storefront.

## Offer tab

Use **Offer** to choose gifts, define how customers receive them, configure qualification rules, set the customer-facing title, and schedule the offer.

### Select gift products

The **Select gift products** section chooses the products offered as gifts.

AIOD notes that gift variants should be active, in stock, and have a price greater than `0`.

Click **+ Select gift products** to choose gift products.

### Gift adding method

The **Gift adding method** section controls how the gift reaches the cart.

| Method                         | Behavior                                                                                                                                     | Extra settings                                                                                                           |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Auto-added**                 | AIOD automatically adds the gift to the cart when the customer qualifies.                                                                    | Shows **Quantity per gift**.                                                                                             |
| **Customer chooses**           | Customers can select their preferred gift from the options provided.                                                                         | Shows **Total gifts customer can choose**.                                                                               |
| **Trigger with discount code** | AIOD adds the gift only when customers enter a specific discount code.                                                                       | Shows discount code fields, usage limits, discount URL, and coupon widget settings.                                      |
| **Code + customer chooses**    | Customers enter the discount code first. If the code is valid, AIOD shows the gift claim widget so the customer can choose and claim a gift. | Shows discount code fields, usage limits, discount URL, coupon widget settings, and **Total gifts customer can choose**. |

### Gift quantity

For **Auto-added** and **Trigger with discount code**, AIOD shows **Quantity per gift**.

For **Customer chooses** and **Code + customer chooses**, AIOD shows **Total gifts customer can choose**.

Both controls use a numeric input. The default shown is `1`.

Enable **Multiply Gift Quantity based on "When" rules** when the gift quantity should scale with the qualification rule. AIOD gives this example: buy 2 get 1 gift, buy 4 get 2 gifts, and so on.

### Free gift settings

The **Free gift settings** section defines when the customer qualifies.

The first choice is what the customer buys:

* **Quantity of items**
* **Purchase amount**

Then choose **Any items from**:

| Option                   | Behavior                          |
| ------------------------ | --------------------------------- |
| **All products**         | Counts all products.              |
| **Specific products**    | Reveals **+ Select products**.    |
| **Specific collections** | Reveals **+ Select collections**. |
| **Specific variants**    | Reveals **+ Select variants**.    |

For **Quantity of items**, AIOD shows:

* **Condition**: **Minimum**, **Maximum**, or **Equals**.
* **Quantity** numeric input.

For **Purchase amount**, AIOD shows:

* **Condition**: **Minimum**, **Maximum**, or **Equals**.
* **Amount \$** numeric input.

Click **AND condition** to add another qualification block. AIOD adds a second condition group and a **Delete AND condition** control.

### Discount code

This section appears when **Trigger with discount code** or **Code + customer chooses** is selected.

Settings:

* **Discount Code** input.
* **Generate random code**.
* **Copy discount code**.
* **Add bulk discount codes**.
* **Maximum Discount Code Uses**.

AIOD notes that the customer must enter this code in the **AIOD Discount Input** widget. The widget can be placed on the cart page and side cart drawer. Read [Discount Code Input](/docs/app/discount-widgets#discount-code-input) for the widget settings.

Bulk-code options:

* **Enter manually**: Enter comma-separated codes.
* **Generate**: Generate many codes with optional prefix, optional suffix, and a code count.

Usage limit settings:

* **Limit number of times this discount can be used in total**: Reveals a numeric input.
* **Limit to one use per customer**: Restricts each customer to one use.

For **Code + customer chooses**, the customer enters the code first. AIOD shows the gift claim widget only after the code is valid.

When a code-based gift method is active, the summary can show:

* **Discount URL**: A storefront URL that applies the discount code automatically.
* **Discount Code Input Widget**: A shortcut to **Coupon Widget Settings**.

### Discount title

The **Discount title** field is shown for non-code gift methods.

AIOD says this title is shown to customers in cart and checkout.

### Schedule

The **Schedule** section controls when the gift offer runs.

Options:

* **Run continuously**: No start/end schedule.
* **Set a schedule**: Reveals **Start date**, **Start time**, **End date**, and **End time**.

## Advance settings tab

Use **Advance settings** for customer eligibility, markets, purchase type, combinations, purchase amount calculation, gift pricing, and cart behavior.

### Customer eligibility

The **Customer eligibility** section controls who can use the offer.

Options:

* **All customers**
* **Specific customers**

When **Specific customers** is selected, AIOD shows a condition builder.

Customer condition types:

* **Customer tags**
* **Customer past orders**
* **Customer email**
* **Customer should be logged in**

For **Customer tags**, operators include:

* **matches any of**
* **matches all of**
* **does not match any of**

The tag input placeholder is `eg- VIP, Gold`.

Optional controls:

* **Apply discount in cart/website without validation & later validate customer eligibility on checkout**.
* **Add condition**.

### Markets

The **Markets** section controls where the offer is available.

Options:

* **All markets**
* **All markets except specific selected countries**
* **Specific selected countries**

The selected-country modes show a **Countries** selector and **Browse** button.

### Purchase type eligibility

The **Purchase Type eligibility** section controls whether subscription and one-time purchase items qualify.

Options:

* **Both**
* **Subscription**
* **One time purchase**

The section also includes **Limit number of subscription cycles**. Leave it blank to allow all subscription cycles.

### How should this discount combine with other discounts?

Read [**This discount can be combined with**](/docs/app/common-template-settings#this-discount-can-be-combined-with) for information about this.

### How to calculate purchase amount

This setting matters when the offer uses a purchase amount rule.

Options:

* **Subtotal before discount**
* **Subtotal after discount**

**Subtotal after discount** was selected by default in the observed form.

### Offer pricing

The **Offer pricing** section controls whether the gift is free or discounted.

Options:

* **Offer as free gift**
* **Offer at a discounted price**

When **Offer at a discounted price** is selected, AIOD shows **Discount percentage %**. The observed default value was `50`.

### Cart refresh and behavior

The **Cart refresh and behavior** section controls cart-side behavior.

Settings:

* **Auto remove**: Automatically removes free gifts if the customer is no longer eligible.
* **Allow gift opt-out**: Allows customers to manually remove free gifts from the cart.

AIOD also shows an **Instant cart refresh** notice. It says the side cart drawer should auto-refresh when a gift is added or removed. If it does not, contact support so theme support can be added.

For global cart reload code, use [**Settings** > **Free gift settings** > **Cart auto reload function (For Developers)**](/docs/app/settings#cart-auto-reload-function). AIOD calls this function each time a gift is added or removed. The code is theme-specific, so developers should add the reload function required by the merchant's theme.

## Widget design tab

Use **Widget design** to configure the storefront gift widget.

### Content

The **Content** sub-tab controls customer-facing widget text and behavior.

Main fields:

* **Banner title**. Default: `Unlock a Free Gift`.
* **Eligible text**. Default: `Meet the offer requirements to unlock your free gift.`
* **Translations**.
* **View available variables**.

Gift display options:

* **Show gift image**.
* **Show currency symbol**.
* **Gift icon type**: **Emoji** or **Custom image URL**.
* **Emoji** input. Default: `🎁`.
* **Image URL** input for custom image URLs. The URL must start with `https://` or `http://`.
* **Icon Size** slider.

Advanced behavior settings:

* **Enable Icon Animation**.
* **Keep Dropdown Open**.
* **Only Show When Valid**.
* **Hide Once Claimed**.
* **Show Banner By Skipping Customer Conditions**.

### Styling

The **Styling** sub-tab controls the banner container.

Settings:

* **Background type**: **Solid color** or **Gradient**.
* **Background color**.
* **Border color**.
* **Border radius**.
* **Shadow style**: **None**, **Light**, **Medium**, **Heavy**, or **Glow Effect**.
* **Internal padding**.

### Typography

The **Typography** sub-tab controls text styling.

Sections:

* **Banner title typography**: title font size, title font weight, title color.
* **Subheading typography**: subheading font size, subheading font weight, subheading color.
* **Gift name typography**: gift name font size, gift name font weight, gift name color.

Font weight options shown were **Normal** and **Bold**.

### Where should the widget appear?

Read [**Where should the widget appear?**](/docs/app/common-template-settings#where-should-the-widget-appear) for information about this.

The widget preview says **Select Gift Items** until gift products are selected.

## Discount summary and rule size

The right-side **Discount Summary** changes as settings change.

It can show:

* How the customer applies the discount.
* Discount type, such as **Free gift** or **Discounted gift**.
* Gift quantity.
* Discount details.
* Combinations.
* Discount URL for code-triggered gifts.
* Coupon widget settings for code-triggered gifts.

AIOD also shows Shopify function rule size information, such as:

* **Rule Size: 1.28 KB / 10 KB**
* **NOTE: This limit is set by Shopify**

Mention rule size when a merchant asks why a gift offer cannot include unlimited logic.

## AI answering guidance

When an AI answers a merchant question about this template:

* Use **Free Gift with Purchase** as the template name.
* Refer to the app page as **Free Gift**.
* Ask how the gift should be added: **Auto-added**, **Customer chooses**, **Trigger with discount code**, or **Code + customer chooses**.
* Ask which product or products should be used as gifts.
* Ask what qualifies the customer: quantity of items or purchase amount.
* Ask whether qualification should count all products, specific products, specific collections, or specific variants.
* Ask about customer eligibility, markets, purchase type, combinations, and schedule only when relevant.
* Mention the widget design tab when the merchant asks how the gift banner appears on the storefront.