Prepare your Shopify storefront for Incentives Builder

Read this page if your storefront, theme, or a third-party app reads subscription discounts from Ordergroove’s Shopify selling plans, such as a headless storefront, a custom theme, or a cart or upsell app. When an offer profile built in Incentives Builder goes live, Ordergroove stops writing the discount to your selling plans, and code that reads it shows the wrong price or breaks. This page explains what changes, how to keep your integration working, and where to read the discount instead. If you’re auditing a store, start with the pre-launch checklist.

How Ordergroove structures selling plans

Ordergroove creates one selling plan group named Subscribe and Save, with merchantCode and appId set to ordergroove-subscribe-and-save. It adds each product variant to the group when the variant becomes subscription eligible in Ordergroove, and creates one selling plan per delivery frequency you offer.

Ordergroove tracks subscription eligibility at the variant level and manages which products and variants its selling plan groups are attached to. Don’t add or remove Ordergroove selling plan groups in Shopify, at either the product or the variant level. Ordergroove doesn’t pick up those changes, and they can prevent subscription orders from being placed.

Field names differ between Shopify’s APIs. This page uses Admin GraphQL names in prose:

Selling plans and subscription contracts

Selling plans are only used up to checkout, where they record that the customer chose a subscription for that line. After checkout, Shopify creates a subscription contract that keeps a copy of the selling plan, and Ordergroove manages recurring orders from that contract. Editing or emptying a selling plan doesn’t change contracts that already exist.

What changes with Incentives Builder

For offer profiles not built in Incentives Builder, Ordergroove writes your initial order discount onto every selling plan as a price adjustment, and describes the discount in the plan name.

Incentives Builder supports incentives that vary by product, by customer group, by how many orders a subscriber has received (for example, a gift on the third order), and by cart threshold, which a single price adjustment can’t represent. When the live offer profile is built in Incentives Builder, Ordergroove applies the initial order discount through a Shopify discount function instead. Your selling plans, existing and new, change accordingly:

• pricingPolicies is set to an empty array (not null).
• Plan names describe the delivery frequency only, for example Delivered every 2 months, with no discount wording. If you’re in Ordergroove’s Early Access program, you can customize plan names instead.
• The initial order discount appears in cart and checkout as a discount from the Ordergroove Subscription Incentives automatic discount, not as a reduced line price.

Before and after

On an existing plan, the pricing policy is removed and the name no longer mentions the discount.

Before:

{
  "id": "gid://shopify/SellingPlan/691288047909",
  "name": "Delivered every 2 months. Get 15% off today and all future orders.",
  "pricingPolicies": [
    {
      "__typename": "SellingPlanFixedPricingPolicy",
      "adjustmentType": "PERCENTAGE",
      "adjustmentValue": { "percentage": 15 }
    }
  ]
}

The plan carries one fixed pricing policy, taken from your initial order discount as a percentage or a fixed amount.

After:

{
  "id": "gid://shopify/SellingPlan/691288047909",
  "name": "Delivered every 2 months",
  "pricingPolicies": []
}

The plan keeps its ID, and the pricing policy and discount wording are gone. Ordergroove’s discount function applies the discount in cart and checkout instead.

Prepaid selling plans don’t change

Prepaid selling plans are built differently, and Incentives Builder doesn’t change them. Each prepaid-eligible variant has its own selling plan group, named Prepaid- followed by the variant ID, with merchantCode ordergroove-prepaid-and-save. Each plan in it covers one prepaid term, and its pricing policy sets the full price for that term rather than discounting the product price.

Check whether these changes apply to your store

These changes apply once an offer profile built in Incentives Builder is live. That includes an existing offer profile that’s been edited in Incentives Builder. The Knowledge Center article Shopify Selling Plans explains the same change without the technical detail.

To check, find your offer profile in RC3. If you can edit it in Incentives Builder, the changes on this page already apply to your store (if that offer profile is live). If RC3 shows an Advanced Flex Incentives warning instead of an edit option, contact Ordergroove to confirm.

You can also check with the API: the list offer profiles endpoint returns is_standardized: true for offer profiles built in Incentives Builder (GET /offer_profiles/?live=true).

Identify common issues

Two common patterns can break your storefront. Check for both before your first Incentives Builder offer profile goes live.

An app or theme shows the wrong discount

This happens with cart, upsell, and bundle apps configured to read the savings from the selling plan, for example a frequency selector labeled Subscribe and Save {{subscription_discount}}% sourced from pricingPolicies[0].adjustmentValue.percentage.

After the change, pricingPolicies is empty, so the app shows the full price, a broken label such as Subscribe and Save % or undefined%, or $NaN where it calculates a price. Customers are still charged the right amount at checkout, so this is easy to miss in testing.

Update the app’s configuration to read the discount from one of the sources in Read incentive data.

The product page breaks

This happens with storefront code that assumes a price adjustment exists:

const percentage =
  sellingPlan.priceAdjustments[0].adjustmentValue.adjustmentPercentage;

After the change, priceAdjustments is empty. Indexing into it returns undefined, and the next property access throws an error such as TypeError: Cannot read properties of undefined (reading 'adjustmentValue'). The wording varies by browser. On a headless storefront, the page can fail to render. In a theme, the error can stop the rest of the script, so later updates such as price or stock labels don’t run.

To prevent the error, guard the whole property chain:

const percentage =
  sellingPlan.priceAdjustments?.[0]?.adjustmentValue?.adjustmentPercentage ?? null;

Liquid doesn’t throw on a missing value. It renders it as blank, so a label like Save {{ selling_plan.price_adjustments[0].value }}% becomes Save %. Check for an adjustment before you use it:

{% assign adjustment = selling_plan.price_adjustments.first %}
{% if adjustment and adjustment.value_type == 'percentage' %}
  Save {{ adjustment.value }}%
{% endif %}

Either guard prevents the broken output, but the page then shows no discount, so use it as a temporary fix. A hard-coded fallback percentage is only correct while it matches your offer profile, including product-specific and conditional discounts. selling_plan_allocation.price and selling_plan_allocation.per_delivery_price no longer reflect the subscription discount either.

Read incentive data

Before the customer adds a product to the cart, read the discount from Ordergroove. Once it’s in the cart, read it from Shopify.

Before the cart, from the offer widget

If your storefront loads the Ordergroove offer widget through main.js (see Offer Tagging), read the discount from it. It runs in the browser and doesn’t need an API key. For offer profiles built in Incentives Builder, the offer response the widget requests includes an incentives_display_enhanced object, keyed by incentive ID. Each entry has incentive_type, incentive_value, incentive_target, threshold_field, threshold_value, and coupon_type (initial or ongoing, where ongoing means recurring). Only conditional incentives have criteria, and the response can include ones the customer doesn’t qualify for, so check criteria before you show a value. The response covers the products on the page, and may not include every incentive in your offer profile.

If your storefront doesn’t load the offer widget, contact Ordergroove to discuss how to show the discount before the cart.

In the cart and checkout

The Ordergroove discount function applies the initial order discount to the cart, so the cart’s applied discounts show exactly what the customer gets. Item-level discounts are allocated to each line, and order-level discounts, such as a threshold discount, are applied to the whole cart:

The Ordergroove discount is titled Ordergroove Subscription Incentives, and each allocation has its configured label, for example Subscription Savings.

Example: show the subscribe price

A $40.00 product, and a program-wide 15% discount on the first order.

Before the cart, in the offer widget’s response, the program-wide discount is the incentives_display_enhanced entry with no criteria, a coupon_type of initial, and an incentive_target of item. Its incentive_value is "15.00", so the subscribe price to show is $34.00.

Product-specific and other conditional discounts are entries with criteria; show one only when the product and customer match it.

In the cart, read the line’s cost and the discount Shopify applied, using the Storefront API:

query CartSubscribePrice($cartId: ID!) {
  cart(id: $cartId) {
    lines(first: 50) {
      nodes {
        cost {
          subtotalAmount { amount }
          totalAmount { amount }
        }
        discountAllocations {
          discountedAmount { amount }
          ... on CartAutomaticDiscountAllocation { title }
        }
      }
    }
  }
}

For the subscription line, subtotalAmount is 40.0, the allocation titled Ordergroove Subscription Incentives has a discountedAmount of 6.0, and totalAmount is 34.0. This is what the customer pays, including product-specific and conditional discounts.

Other behavior changes

Line item prices

The initial order discount is applied as a discount, not a price adjustment, so line item prices don’t include it. If your code detects a subscription discount from line item prices, read the applied discounts instead.

Recurring subtotal

Shopify’s recurring subtotal in checkout doesn’t include Ordergroove incentives, and you can’t change the value. You can change the labels around it; see Integrating with Shopify Checkout.

Pre-launch checklist

Before your first Incentives Builder offer profile goes live, check for:

• Apps that display a discount read from the selling plan, such as cart, upsell, bundle, loyalty, or other subscription apps
• Storefront code that reads pricingPolicies, priceAdjustments, or selling plan allocation prices without a guard
• Hard-coded discount fallbacks that won’t match conditional or product-specific incentives
• Code, translation files, or reports that parse or key on selling plan names
• Places that show plan names to customers, such as the cart, checkout, or emails, where the discount wording will no longer appear
• Logic that detects a subscription discount from line item prices

Test in a development store first. Contact Ordergroove to have Incentives Builder enabled on that store.

We recommend building a new offer profile in Incentives Builder rather than editing your live one. The previous profile then stays available, and you can make it live again if something breaks.

Related resources

• Shopify Selling Plans in the Knowledge Center
• Handling Shopify product variants in the Knowledge Center
• Integrating with Shopify Checkout
• Offer Tagging
• Selling plans in Shopify’s developer documentation