Skip to content

Migrate Shopify Scripts to Functions: your discounts, step by step

Update/ 18 min read

Scripts stopped running on June 30, 2026. How to rebuild a volume promotion as a discount Function, and stack discounts on one cart line since Admin API 2026-04.

  • Shopify Functions
  • Shopify Plus
  • Checkout
  • Migration
In this article (9)
  1. What happened to Shopify Scripts
  2. What Shopify discount Functions are
  3. Multiple product discounts on the same cart line
  4. combinesWith: what each discount combines with
  5. Migrate a Scripts promotion step by step
  6. Test it on a dev store
  7. Common mistakes
  8. Frequently asked questions
  9. Checklist

To migrate Shopify Scripts to Functions, rebuild each promotion as a discount Function: an input query, a function that returns discount candidates, and a discount created with its combination rules. Scripts stopped running on June 30, 2026, and since Admin API 2026-04, several product discounts can share one cart line on Shopify Plus.

This post covers what Shopify announced and when, what a discount Function is, how stacked discounts on one line and combinesWith work, and a full migration of a real Scripts promotion: a volume discount we rewrote in JavaScript and ran in Node against five carts. If you are not sure your case needs a Function at all, start with when a Shopify Function is the right tool.

What happened to Shopify Scripts

On April 9, 2026, Shopify posted "Shopify Scripts will be deprecated on June 30, 2026" to its changelog, with two separate dates: from April 15, Scripts could no longer be edited or published, and on June 30 every Script stopped executing. The Help Center page it linked to, now titled App extensions and functions, puts it in the past tense: scripts no longer run on any store. If a promotion lived in a Script and nobody migrated it, checkout has been charging without it since July 1.

On April 30, the changelog announced "Multiple product discounts can apply on a single cart line": as of version 2026-04 of the GraphQL Admin API, several product discounts can apply to the same cart line, so merchants could keep migrating Scripts ahead of the sunset. And on September 10, Shopify closed the Discounts Allocator Function API developer preview; it will not be released, and discount allocation stays with the platform. If your app declares the purchase.discounts-allocator.run target, remove it, or shopify app deploy fails for the whole app.

DateWhat happenedWhere Shopify says so
Apr 15, 2026Scripts can no longer be edited or published.April 9 changelog
Apr 30, 2026Admin API 2026-04: multiple product discounts on one cart line.April 30 changelog
Jun 30, 2026All Scripts stop executing.April 9 changelog
Sep 10, 2026Discounts Allocator preview closes; allocation stays with the platform.September 10 changelog

Updated November 11, 2026: the April post pointed to the Scripts customizations report and a Help Center migration guide; that page no longer mentions the report and only confirms the retirement. The current Discount Function API reference is version 2026-10, which is what the official tutorial uses and what we use here.

Do not confuse Ruby Scripts with script tags: that is a separate retirement on its own timeline, covered in Shopify Scripts and script tags have different deprecation deadlines.

What Shopify discount Functions are

A discount Function is an app extension that Shopify runs on its own servers every time it prices a cart. You do not hand the line a new price, the way a Script did: you return operations, and Shopify decides how to apply them. The Discount Function API reference has two run targets: cart.lines.discounts.generate.run for cart lines and the order subtotal, and cart.delivery-options.discounts.generate.run for delivery. The fetch targets, with network access, are limited to custom apps on Shopify for enterprise stores; you do not need them to migrate a Script.

Which target runs is decided by the discount, not by your code: per Shopify's discounts documentation, the discount's discountClasses field determines which targets execute. The PRODUCT and ORDER classes come from the cart lines target; SHIPPING from the delivery one.

Each target has an input query (the data your logic uses; whatever you do not ask for does not exist for your function), the function itself (in JavaScript, cartLinesDiscountsGenerateRun), and what it returns: operations such as productDiscountsAdd or orderDiscountsAdd, holding candidates. A candidate says what it applies to (a cartLine, the orderSubtotal, or a deliveryOption), how much (percentage or fixedAmount), and the message the customer sees. For product discounts, the selectionStrategy is FIRST (the first candidate), MAXIMUM (the biggest reduction) or ALL (every candidate, without overriding combination or stacking rules). Decimals are written as strings: "10.0".

Three limits from the reference: a discount Function controls only the discounts it creates, not native ones or another app's; Functions run concurrently and know nothing about each other; and if a run fails, Shopify discards its output, the discount does not apply, and checkout carries on.

Multiple product discounts on the same cart line

By default, a cart line gets one product discount. If two discounts qualify for the same t-shirt, one of them applies. For plenty of promotions that came from Scripts, that was a blocker, and it is what changed with API 2026-04.

The new piece is the productDiscountsWithTagsOnSameCartLine field inside combinesWith. The rules, per the Admin API reference:

  • It is available only on the Shopify Plus plan and requires productDiscounts: true. The changelog post does not mention Plus; the reference and the Help Center do.
  • It works with tags, in both directions. Each discount has its own tags (the tags field) and a list of tags it agrees to share a line with. Two discounts apply together only if each one allows at least one tag the other carries.
  • Any number of discounts can stack on one line, as long as every pair passes that check.
  • In a Buy X Get Y discount, only the products the customer gets stack, not the ones they buy.

What order are they calculated in? The Help Center's Combining discounts page says product discounts come first, then order discounts, then shipping. On the same item, percentages apply before fixed amounts, and the fixed amount comes off the already reduced price. Its example: $100 pants with a 10% clothing discount drop to $90, and a $20 pants discount takes them to $70.

one cart line, two discounts: the percentage goes before the fixed amountt-shirt × 3$300.0010% volume tier−$30.00Function · tag volumeof $300.00$20 loyalty−$20.00another discount · tag loyaltyof $270.00line total$250.00reciprocal tagsvolumeloyaltyloyaltyvolumeeach one allowsthe other one's tagrequiresShopify PlusAdmin API 2026-04productDiscounts: truepercentage first, then the fixed amount on the reduced priceillustrative example · calculation order from the Shopify Help Center

Scroll the figure sideways to see all of it

The part that matters for your Function: this change lives in the discount's configuration, not in what the function returns. Your code keeps returning its candidates exactly as before. Whether they share a line with another discount is decided by combinesWith and by each discount's tags.

In the admin, the steps are: open the discount, add a tag under Tags, check Product discounts under Combinations, switch One per product to Multiple per product, and pick the tags to combine with under Combine on same product with discounts tagged. The other discount needs the reciprocal setup.

combinesWith: what each discount combines with

Every discount, native or app-based, has a combinesWith. In DiscountCombinesWithInput (API 2026-04) there are four fields:

FieldTypeWhat it controls
productDiscountsBoolean, defaults to falseWhether it combines with product-class discounts.
orderDiscountsBoolean, defaults to falseWhether it combines with order-class discounts.
shippingDiscountsBoolean, defaults to falseWhether it combines with shipping discounts.
productDiscountsWithTagsOnSameCartLine{ add, remove }Which tags it agrees to share a cart line with. Plus only; requires productDiscounts: true.

add and remove edit the list of allowed tags, not the discount's own tags. Those go in the tags field of DiscountAutomaticAppInput, or of whichever discount input you are using. Careful: updating tags overwrites the existing ones; to append, the reference points to the tagsAdd mutation.

Two more Help Center rules apply to app discounts: when an app creates one discount with several classes, it combines only with discounts that allow all of those classes, and a store can have up to 25 active automatic discounts, app discounts included. Write the combinations down before you write code: does this promotion add up with the newsletter code? With the loyalty discount, on the same line?

Migrate a Scripts promotion step by step

The example is one of the most common line item Scripts: a volume discount on tagged products. Three to five units on a line get 10% off; six or more get 15%; gift cards never qualify. Here is the Script, written with the same calls Shopify's archived Script examples on GitHub use. It cannot run on any store anymore, so we did not run it:

TAG = 'bulk-tier'
TIERS = [
  { min_quantity: 6, percentage: 15 },
  { min_quantity: 3, percentage: 10 },
]

Input.cart.line_items.each do |line_item|
  product = line_item.variant.product
  next if product.gift_card?
  next unless product.tags.include?(TAG)

  tier = TIERS.find { |t| line_item.quantity >= t[:min_quantity] }
  next if tier.nil?

  line_item.change_line_price(
    line_item.line_price * (1.0 - tier[:percentage] / 100.0),
    message: "#{tier[:percentage]}% off for #{tier[:min_quantity]}+"
  )
end

Output.cart = Input.cart
  1. TAG and TIERS are the settings, hard-coded: changing a tier meant editing and republishing the Script.
  2. The loop walks every cart line and skips gift cards and products without the tag.
  3. TIERS.find takes the first tier the line's quantity reaches, which is why the 6-unit tier comes first.
  4. change_line_price rewrites the line price with a message. The Script did not create a discount; it changed the price.
  5. Output.cart = Input.cart hands the modified cart back.

Step 1: write the rule in plain words

Before you open a terminal: "Products tagged bulk-tier: 10% off with 3 to 5 units on the line, 15% with 6 or more; never gift cards; combines with the loyalty discount on the same line." That last clause was not in the Script, and now it is discount configuration, not code.

Step 2: generate the extension

From your app folder, with the Shopify CLI:

shopify app generate extension --template discount --flavor vanilla-js --name volume-discount
  1. --template discount uses the Discount Function API template.
  2. --flavor vanilla-js picks JavaScript; the CLI also takes typescript and rust, among others.
  3. --name is the extension's name; the CLI creates it in a folder under extensions/.

The JavaScript template ships with both targets. This promotion only needs the cart lines one, so we remove the delivery target, the same way Shopify does in its Build a Discount Function that rejects invalid codes tutorial: drop its block from the TOML, its two src/cart_delivery_options* files and its line in src/index.js.

Step 3: the input query

In src/cart_lines_discounts_generate_run.graphql:

query CartInput {
  cart {
    lines {
      id
      quantity
      merchandise {
        __typename
        ... on ProductVariant {
          product {
            isGiftCard
            hasAnyTag(tags: ["bulk-tier"])
          }
        }
      }
    }
  }
  discount {
    discountClasses
    metafield(namespace: "$app", key: "volume-tiers") {
      jsonValue
    }
  }
}
  1. query CartInput is the operation name the JavaScript template uses.
  2. For each line we ask for id, to target the discount, and quantity, to pick the tier.
  3. merchandise can be a variant or another kind of merchandise; __typename tells you which.
  4. Tags are not readable as a list: hasAnyTag returns true when the product has any of the tags you pass. isGiftCard replaces the Script's gift_card?.
  5. discountClasses tells you which classes the discount was created with.
  6. The discount's volume-tiers metafield, in the $app namespace, holds the tiers as JSON; jsonValue hands it over already parsed.

Step 4: the function

In src/cart_lines_discounts_generate_run.js:

// The tiers the Script had as constants. A "volume-tiers" metafield on the discount overrides them.
const DEFAULT_TIERS = [
  { minQuantity: 6, percentage: 15 },
  { minQuantity: 3, percentage: 10 },
];

export function cartLinesDiscountsGenerateRun(input) {
  if (!input.discount.discountClasses.includes("PRODUCT")) {
    return { operations: [] };
  }

  const tiers = [...(input.discount.metafield?.jsonValue?.tiers ?? DEFAULT_TIERS)]
    .sort((a, b) => b.minQuantity - a.minQuantity);

  const candidates = [];
  for (const line of input.cart.lines) {
    if (line.merchandise.__typename !== "ProductVariant") continue;
    const { product } = line.merchandise;
    if (product.isGiftCard || !product.hasAnyTag) continue;

    const tier = tiers.find((t) => line.quantity >= t.minQuantity);
    if (!tier) continue;

    candidates.push({
      message: `${tier.percentage}% off for ${tier.minQuantity}+`,
      targets: [{ cartLine: { id: line.id } }],
      value: { percentage: { value: tier.percentage.toFixed(1) } },
    });
  }

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

  return {
    operations: [{ productDiscountsAdd: { candidates, selectionStrategy: "ALL" } }],
  };
}
  1. DEFAULT_TIERS are the Script's tiers. If the discount has the metafield, its tiers win, so the merchant can change them without a deploy.
  2. If the discount does not include the PRODUCT class, we return { operations: [] }: nothing to do.
  3. The tiers are sorted from the highest minimum down, so find picks the highest tier reached whatever order the JSON uses.
  4. We skip anything that is not a variant, gift cards, and products without the tag.
  5. Each qualifying line gets a candidate: its cartLine, the percentage as a string via toFixed(1), and the message the customer sees.
  6. No candidates, no operation. Otherwise one productDiscountsAdd with selectionStrategy: "ALL": every line has its own candidate and we want all of them applied. With FIRST, only the first would apply.

The template imports DiscountClass and the strategy enums from ../generated/api, a file generated by shopify app function typegen. Here we write the same values as strings so the function runs in plain Node without that step.

Step 5: the extension config

The shopify.extension.toml, without the delivery target:

api_version = "2026-10"

[[extensions]]
name = "t:name"
handle = "volume-discount"
type = "function"
description = "t:description"

  [[extensions.targeting]]
  target = "cart.lines.discounts.generate.run"
  input_query = "src/cart_lines_discounts_generate_run.graphql"
  export = "cart-lines-discounts-generate-run"

  [extensions.build]
  command = ""
  path = "dist/function.wasm"
  1. api_version = "2026-10" is the Discount Function API version. The official tutorial uses 2026-10; the GitHub template still ships 2026-07.
  2. handle identifies the Function; you pass it as functionHandle when you create the discount.
  3. The single [[extensions.targeting]] block ties the cart lines target to its query and to the cart-lines-discounts-generate-run export, which maps to the cartLinesDiscountsGenerateRun function.
  4. [extensions.build] stays as in the template: the CLI compiles the JavaScript to dist/function.wasm.
from a Ruby Script to a discount Function, in six stepsread the Script, write the rule in prosebulk-tier: 3+ = 10%, 6+ = 15%generate the discount extensionshopify app generate extension --template discount --flavor vanilla-jsask only for the data it uses: input queryquantity · hasAnyTag(tags: ["bulk-tier"]) · metafieldreturn candidates, not pricesproductDiscountsAdd · selectionStrategy: ALLcreate the discount and what it combines withdiscountAutomaticAppCreate · discountClasses · combinesWithtest it on a dev storeshopify app dev · shopify app function replaythe rule stays; what applies the discount changesthe function was run in Node against 5 sample carts

Scroll the figure sideways to see all of it

the same discount promotion in Scripts and in FunctionsScriptsFunctionslanguageRubyJavaScript, TypeScript, Rustwhere it livesScript Editor (app)an app extensionthe promotionchange_line_priceproductDiscountsAddoutputOutput.cartoperations (JSON)settingsconstants in the codea discount metafieldstatusoff since Jun 30, 2026API 2026-10a Script changed the price; a Function returns discountsFunctions also cover delivery and payments; this table is about discounts

Scroll the figure sideways to see all of it

Test it on a dev store

First, in Node

The function is pure: JSON in, JSON out. Before you compile anything, you can call it from Node with sample carts. Save each cart in inputs/ in the exact shape your query returns. This is the multi-line cart, inputs/cart-mixed.json:

{
  "cart": {
    "lines": [
      { "id": "gid://shopify/CartLine/1", "quantity": 6,
        "merchandise": { "__typename": "ProductVariant", "product": { "isGiftCard": false, "hasAnyTag": true } } },
      { "id": "gid://shopify/CartLine/2", "quantity": 3,
        "merchandise": { "__typename": "ProductVariant", "product": { "isGiftCard": false, "hasAnyTag": true } } },
      { "id": "gid://shopify/CartLine/3", "quantity": 10,
        "merchandise": { "__typename": "ProductVariant", "product": { "isGiftCard": true, "hasAnyTag": true } } },
      { "id": "gid://shopify/CartLine/4", "quantity": 1,
        "merchandise": { "__typename": "ProductVariant", "product": { "isGiftCard": false, "hasAnyTag": true } } },
      { "id": "gid://shopify/CartLine/5", "quantity": 8,
        "merchandise": { "__typename": "CustomProduct" } }
    ]
  },
  "discount": { "discountClasses": ["PRODUCT"], "metafield": null }
}
  1. Lines 1 and 2 carry the tag with 6 and 3 units: they should get 15% and 10%.
  2. Line 3 is a gift card, line 4 has 1 unit, and line 5 is not a variant (CustomProduct, no product): none of them should get anything.
  3. "metafield": null stands for a discount without settings: the default tiers apply.

The other four carts (they are in the guide) cover a line that qualifies, one that does not, a metafield with a different tier, and an ORDER-only discount. This run-carts.mjs, next to package.json, runs them all:

import { readdirSync, readFileSync } from "node:fs";
import { cartLinesDiscountsGenerateRun } from "./src/cart_lines_discounts_generate_run.js";

for (const file of readdirSync("inputs")) {
  const input = JSON.parse(readFileSync(`inputs/${file}`, "utf8"));
  const { operations } = cartLinesDiscountsGenerateRun(input);
  const candidates = operations[0]?.productDiscountsAdd.candidates ?? [];
  console.log(file, candidates.map((c) => `${c.targets[0].cartLine.id} ${c.value.percentage.value}%`));
}
  1. It imports the function directly, without compiling it; the template's package.json already sets "type": "module".
  2. It reads each JSON file in inputs/, calls the function, and prints which line gets which percentage, or an empty list.

This is the real output, on Node 22.22.3 and Windows 11:

$ node run-carts.mjs
cart-config.json [ 'gid://shopify/CartLine/1 5.0%' ]
cart-mixed.json [ 'gid://shopify/CartLine/1 15.0%', 'gid://shopify/CartLine/2 10.0%' ]
cart-no-match.json []
cart-order-only.json []
cart-qualifies.json [ 'gid://shopify/CartLine/1 10.0%' ]
  1. cart-config: the metafield has a single tier (2 or more, 5%) and overrides the defaults.
  2. cart-mixed: only lines 1 and 2 get a candidate, at 15% and 10%.
  3. cart-no-match and cart-order-only: the function returns { operations: [] }; in the second, because the discount lacks the PRODUCT class.
  4. cart-qualifies: 4 tagged units, 10%.

We also validated the query against the 2026-04 and 2026-07 Discount Function API schemas, and checked that every cart has exactly the shape that query returns and that every output is a valid CartLinesDiscountsGenerateRunResult.

The next local step is running the compiled function with the Shopify CLI, from the extension folder:

shopify app function run --input inputs/cart-mixed.json --export cart-lines-discounts-generate-run
  1. --input passes the cart JSON; without it, the CLI reads standard input.
  2. --export is the export value from the TOML.

We did not run that command: it runs inside a CLI app project, and for this post we did not create an app or connect a store.

Then, on a dev store

Testing several discounts on one line needs Plus. From the Dev Dashboard you can create a dev store and choose its plan, Plus included. Dev stores do not process real transactions; you pay with the test payment gateway. Following the Discount Function tutorial: run shopify app dev, press g in that terminal to open GraphiQL, pick the latest stable API version, and create the discount:

mutation CreateVolumeDiscount {
  discountAutomaticAppCreate(
    automaticAppDiscount: {
      title: "Volume discount"
      functionHandle: "volume-discount"
      discountClasses: [PRODUCT]
      startsAt: "2026-11-11T00:00:00Z"
      tags: ["volume"]
      combinesWith: {
        productDiscounts: true
        productDiscountsWithTagsOnSameCartLine: { add: ["loyalty"] }
      }
      metafields: [
        {
          namespace: "$app"
          key: "volume-tiers"
          type: "json"
          value: "{\"tiers\":[{\"minQuantity\":6,\"percentage\":15},{\"minQuantity\":3,\"percentage\":10}]}"
        }
      ]
    }
  ) {
    automaticAppDiscount {
      discountId
      status
      combinesWith {
        productDiscounts
        productDiscountsWithTagsOnSameCartLine
      }
    }
    userErrors {
      field
      message
    }
  }
}
  1. functionHandle is the handle from the TOML.
  2. discountClasses: [PRODUCT] means only the cart lines target runs and the function returns product discounts.
  3. tags: ["volume"] is this discount's own tag.
  4. combinesWith lets it combine with other product discounts and, on the same line, with discounts tagged loyalty.
  5. metafields stores the tiers in $app / volume-tiers, the metafield the query reads. To change them, update this value; no deploy needed.
  6. Check userErrors. If it says "Could not find Function", the tutorial says to confirm app dev is still running, the handle is right, and the app has the write_discounts scope.

Then, in the admin, create the other product discount (say, $20 off t-shirts) tagged loyalty, with Multiple per product and discounts tagged volume. Deactivate other discounts and try 2, 4 and 6 units, then 6 with the loyalty discount active. Check each run in the shopify app dev output and replay it with shopify app function replay. Test the stacking before you promise it: it depends on how each discount is configured.

Common mistakes

  • Using FIRST with one candidate per line. Only the first applies. When every line has its own candidate, use ALL.
  • Creating the discount without the PRODUCT class. discountClasses decides which targets run; with only ORDER, this function returns nothing.
  • Writing decimals as numbers. The reference documents the string form: "15.0".
  • Asking for the product's tags in the query. The schema does not have it; use hasAnyTag or hasTags.
  • Setting tags in one direction only. Each discount has to allow a tag the other one carries.
  • Updating tags to add one. It replaces the existing tags; use tagsAdd.
  • Promising stacked discounts without Plus or without productDiscounts: true. Same-line stacking needs both.

Frequently asked questions

Do my Shopify Scripts still work?

No. Per Shopify's changelog, Scripts could not be edited or published from April 15, 2026, and none have run since June 30, 2026. If a promotion depended on a Script and was never migrated, it is not applying today.

Do I need Shopify Plus?

For several product discounts on the same cart line, yes: the Admin API reference limits it to the Plus plan. For the Function itself, it depends on how you distribute it, which we cover in when a Shopify Function is the right tool.

Can I write the Function in JavaScript?

Yes. The CLI generates the extension with --flavor vanilla-js, typescript or rust, and compiles JavaScript to WebAssembly. Shopify's JavaScript template is the base of this example.

How do I test it without touching the live store?

In three layers: call the function from Node with JSON carts, run the compiled build with shopify app function run, and test on a dev store with shopify app dev. For same-line stacking, create the dev store on the Plus plan.

Checklist

  • You have the list of promotions that lived in Scripts, each one written out in plain words.
  • The extension has only the targets it uses and api_version = "2026-10".
  • The input query asks only for what the function uses and validates against the schema.
  • The function returns decimals as strings, and ALL when there is one candidate per line.
  • You ran the function in Node with carts that qualify, carts that do not, and multi-line carts.
  • The discount is created with discountClasses, tags, combinesWith and the tiers metafield.
  • Discounts that stack on one line have reciprocal tags, and the store is on Plus.
  • You tested on a dev store and checked the runs with shopify app function replay.

If you want merchants to edit the tiers from a screen in your app instead of a mutation, see the Polaris 2 release candidate for Shopify apps. To decide whether a rule needs a Function or something simpler, read when a Shopify Function is the right tool. And if your store also relied on script tags, check the two retirements and their dates.

If the promotion needs input from the shopper at checkout, see how to add a custom field with a checkout UI extension.

Saw this on Instagram? Comment FUNCTIONS on the Reel and I'll send you the guide.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 11, 2026 · updated November 18, 2026

← Blog