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. However, if you want to customize your customer experience further, we recommend using Shopify 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.

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.

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.

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 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:

   1
   query CartInput {
   2
     cart {
   3
       lines {
   4
         id
   5
         quantity
   6
         sellingPlanAllocation {
   7
           sellingPlan {
   8
             id
   9
             name
   10
           }
   11
         }
   12
         merchandise {
   13
           __typename
   14
           ... on ProductVariant {
   15
             id
   16
             title
   17
           }
   18
         }
   19
       }
   20
     }
   21
   }

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

   1
   import { ProductDiscountSelectionStrategy } from '../generated/api';
   2
   3
   /**
   4
    * @typedef {import('../generated/api').Input} Input
   5
    * @typedef {import('../generated/api').CartLinesDiscountsGenerateRunResult} CartLinesDiscountsGenerateRunResult
   6
    */
   7
   8
   /**
   9
    * cartLinesDiscountsGenerateRun
   10
    *
   11
    * If a cart line has a sellingPlanAllocation (i.e. it's on a subscription / has a selling plan),
   12
    * apply a flat 20% discount to that line.
   13
    *
   14
    * @param {Input} input
   15
    * @returns {CartLinesDiscountsGenerateRunResult}
   16
    */
   17
   export function cartLinesDiscountsGenerateRun(input) {
   18
     const DISCOUNT_PERCENTAGE = 20; // 20%
   19
     const candidates = [];
   20
   21
     if (!input.cart?.lines || input.cart.lines.length === 0) {
   22
       return { operations: [] };
   23
     }
   24
   25
     for (const line of input.cart.lines) {
   26
       // Only consider product variants with a selling plan allocation
   27
       if (
   28
         line.merchandise.__typename !== 'ProductVariant' ||
   29
         !line.sellingPlanAllocation
   30
       ) {
   31
         continue;
   32
       }
   33
   34
       const variant = line.merchandise;
   35
       const message = variant.title
   36
         ? `${DISCOUNT_PERCENTAGE}% off subscription for ${variant.title}!`
   37
         : `${DISCOUNT_PERCENTAGE}% off this subscription!`;
   38
   39
       candidates.push({
   40
         value: {
   41
           percentage: { value: 20 }
   42
         },
   43
         targets: [
   44
           {
   45
             productVariant: {
   46
               id: variant.id,
   47
               quantity: line.quantity
   48
             }
   49
           }
   50
         ],
   51
         message
   52
       });
   53
     }
   54
   55
     if (candidates.length === 0) {
   56
       return { operations: [] };
   57
     }
   58
   59
     return {
   60
       operations: [
   61
         {
   62
           productDiscountsAdd: {
   63
             candidates,
   64
             selectionStrategy: ProductDiscountSelectionStrategy.First
   65
           }
   66
         }
   67
       ]
   68
     };
   69
   }

9. Run shopify app deploy

Further Customizations

For further customizations, see Shopify’s documentation on the Functions API. You’ll find great examples of building functions that you can adapt for your subscription program.

Related Articles

• Shopify’s guide on Functions
• Shopify’s Function API docs