> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ordergroove.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server.

# Customizing the Initial Offer Incentive (IOI)

If you are trying to offer your customers an Initial Offer Incentive, you may be able to use [our feature in the Ordergroove Admin](https://help.ordergroove.com/hc/en-us/articles/4406884025363). However, if you want to customize your customer experience further, we recommend using [Shopify Functions](https://shopify.dev/docs/apps/build/functions).

Shopify Functions inject code into the backend logic of Shopify, allowing you to create unique experiences for your customers in their cart and at checkout. Find out more in [Shopify's Help Center](https://help.shopify.com/en/manual/checkout-settings/script-editor).

#### Looking for the legacy Shopify Scripts version?

If you are maintaining an existing implementation or migrating from Shopify Scripts, you can still access the original [Scripts-based guide here](https://developer.ordergroove.com/docs/copy-of-customizing-the-initial-offer-incentive-ioi). Please note that Scripts will stop functioning on June 30, 2026.

***

## Requirements

Shopify Functions require a custom app or a paid app from the Shopify App Store. Custom apps can only be made by Shopify Partners — this guide is intended for developers working with Shopify clients.

***

## Getting Started

Shopify Functions allow developers to customize the backend logic of Shopify. Functions are continually being updated, so it is best to first reference Shopify's official [documentation](https://shopify.dev/docs/apps/build/functions).

At a high level:

* App developers create and deploy apps that contain functions.
* Merchants install the app on their Shopify store and configure the function via an API call.
* Customers interact with the Shopify store and Shopify executes the function.

You can use Shopify apps to generate functions, or create your own for complete control. For an Initial Offer Incentive (IOI) you will need a Discount Function.

Read the full documentation on creating a [Shopify Discount Function](https://shopify.dev/docs/apps/build/discounts/build-discount-function?extension=javascript).

The following is a quick start guide for creating a basic Discount Function app that discounts subscription line items by 20%. This can be combined with the [Free Shipping on Initial Orders](/docs/lifecycle/enrollment/free-shipping) Discount Function.

**Note:** This guide is accurate as of Shopify Function API version 2026-01.

1. Use Shopify CLI version 3.69.4+

2. Use Node version 22.9.9+

3. Navigate to a local directory where you want to create the app

4. Run `shopify app init` to create an app:
   1. Select **Build an extension-only app**
   2. Select **Yes, create it as a new app**
   3. Name your app (e.g. `ordergroove-discount`)
   4. The app will now appear in your Shopify Partner Dashboard

5. Run `cd ordergroove-discount`

6. Run `shopify app generate extension`:
   1. Select the extension to create
   2. Name your extension
   3. Select a language *(the example code below assumes JavaScript)*

7. Edit `ordergroove-discount/src/cart_lines_discounts_generate_run.graphql` — replace the full file with:

   ```graphql
   query CartInput {
     cart {
       lines {
         id
         quantity
         sellingPlanAllocation {
           sellingPlan {
             id
             name
           }
         }
         merchandise {
           __typename
           ... on ProductVariant {
             id
             title
           }
         }
       }
     }
   }
   ```

8. Edit `ordergroove-discount/src/cart_lines_discounts_generate_run.js` — replace the full file with:

   ```javascript
   import { ProductDiscountSelectionStrategy } from '../generated/api';

   /**
    * @typedef {import('../generated/api').Input} Input
    * @typedef {import('../generated/api').CartLinesDiscountsGenerateRunResult} CartLinesDiscountsGenerateRunResult
    */

   /**
    * cartLinesDiscountsGenerateRun
    *
    * If a cart line has a sellingPlanAllocation (i.e. it's on a subscription / has a selling plan),
    * apply a flat 20% discount to that line.
    *
    * @param {Input} input
    * @returns {CartLinesDiscountsGenerateRunResult}
    */
   export function cartLinesDiscountsGenerateRun(input) {
     const DISCOUNT_PERCENTAGE = 20; // 20%
     const candidates = [];

     if (!input.cart?.lines || input.cart.lines.length === 0) {
       return { operations: [] };
     }

     for (const line of input.cart.lines) {
       // Only consider product variants with a selling plan allocation
       if (
         line.merchandise.__typename !== 'ProductVariant' ||
         !line.sellingPlanAllocation
       ) {
         continue;
       }

       const variant = line.merchandise;
       const message = variant.title
         ? `${DISCOUNT_PERCENTAGE}% off subscription for ${variant.title}!`
         : `${DISCOUNT_PERCENTAGE}% off this subscription!`;

       candidates.push({
         value: {
           percentage: { value: 20 }
         },
         targets: [
           {
             productVariant: {
               id: variant.id,
               quantity: line.quantity
             }
           }
         ],
         message
       });
     }

     if (candidates.length === 0) {
       return { operations: [] };
     }

     return {
       operations: [
         {
           productDiscountsAdd: {
             candidates,
             selectionStrategy: ProductDiscountSelectionStrategy.First
           }
         }
       ]
     };
   }
   ```

9. Run `shopify app deploy`

### Further Customizations

For further customizations, see [Shopify's documentation on the Functions API](https://shopify.dev/docs/api/functions/latest). You'll find great examples of building functions that you can adapt for your subscription program.

***

## Related Articles

* [Shopify's guide on Functions](https://shopify.dev/docs/apps/build/functions)
* [Shopify's Function API docs](https://shopify.dev/docs/api/functions/latest)