Shopify Scripts to Functions: The Technical Migration Guide for Plus Engineers

Shopify Scripts and Shopify Functions are not the same product with a new name. They are different in five fundamental ways, and every one of them affects how you migrate.

Scripts ran in a Ruby sandbox hosted by Shopify. You wrote Ruby, pasted it into the admin, hit save. Shopify executed it at cart and checkout, in a tightly limited environment with no network, no storage, and no app context.

Functions run as WebAssembly modules. You write Rust or JavaScript, compile to WASM, and Shopify executes that bytecode inside its checkout pipeline. The sandbox is even tighter than Scripts: no network, no storage, sub-millisecond execution targets, hard CPU and memory limits.

Scripts were edited in the Plus admin. There was no version control, no deployment step, no CI. You pasted Ruby into a text box and clicked save. Audit trail: a few admin log entries.

Functions are deployed via the Shopify CLI as part of a custom app. Source lives in your repo. Builds run in CI. Deployments are explicit. Rollback is a redeploy of a previous version.

Scripts had no app association. They lived under the merchant’s Plus admin, edited by anyone with the right role.

Functions are app-scoped. You build a Shopify app (custom or public), the Function lives inside that app, and the app gets installed on the store with specific scopes. The merchant’s admin shows the Function as part of the app’s UI surface. No app, no Function.

The Shopify Scripts API exposed Input.cart, Input.cart.customer, Input.cart.line_items as Ruby objects you could read and mutate.

Functions take a GraphQL input at the top of the WASM module and return a mutation operation. The shapes are strictly typed, the inputs are configured per-Function, and the output schema is defined by the Function target (e.g. cart.lines.discounts.generate.run, cart.delivery-options.transform.run, cart.checkout.payment-methods.transform.run).

Scripts ran as one combined Ruby file with implicit ordering. Functions are independent units. Multiple Functions can target the same surface, and Shopify merges their output according to documented rules (e.g. discount Functions stack additively unless one returns Replace).

Install the Shopify CLI. The current version handles Function generation out of the box.

npm install -g @shopify/cli@latest shopify version

Create or pick a Shopify app to host the Functions. If you do not already have a custom app, create one:

shopify app init --name=plus-functions-migration cd plus-functions-migration

Inside the app, generate a Function with the type matching what you are migrating:

# Discount Function (replaces Line Item Scripts) shopify app generate extension --type=product_discounts --name=tier-discount # Delivery Customization (replaces Shipping Scripts) shopify app generate extension --type=delivery_customization --name=region-shipping # Payment Customization (replaces Payment Scripts) shopify app generate extension --type=payment_customization --name=hide-cod-international

For each Function you generate, the CLI scaffolds a directory with:

• shopify.extension.toml (Function metadata, target, input config)
• src/main.rs or src/index.js (the Function body)
• input.graphql (the GraphQL query that defines what your Function receives)
• package.json or Cargo.toml (dependencies)

This is the most common migration. Here is a real Script we have seen in the wild:

# Legacy Shopify Script: tier_gold customer gets 15% off Input.cart.line_items.each do |line_item| if Input.cart.customer && Input.cart.customer.tags.include?("tier_gold") discount = line_item.line_price * 0.15 line_item.change_line_price( line_item.line_price - discount, message: "Tier Gold discount" ) end end Output.cart = Input.cart

The equivalent Discount Function in Rust looks structurally different. You query the input, generate a discount operation, return it. The Function does not mutate the cart; it tells Shopify what discount to apply, and Shopify applies it.

First the GraphQL input query (input.graphql), which tells Shopify what data to pass to your Function:

query Input { cart { buyerIdentity { customer { hasTag(tag: "tier_gold") } } lines { id cost { amountPerQuantity { amount } } } } }

Then the Function body in Rust (src/main.rs, abbreviated):

use shopify_function::prelude::*; #[shopify_function] fn cart_lines_discounts_generate_run( input: input::ResponseData, ) -> Result<output::CartLinesDiscountsGenerateRunResult> { let has_tier_gold = input .cart .buyer_identity .as_ref() .and_then(|b| b.customer.as_ref()) .map(|c| c.has_tag) .unwrap_or(false); if !has_tier_gold { return Ok(output::CartLinesDiscountsGenerateRunResult { operations: vec![], }); } let targets: Vec<_> = input .cart .lines .iter() .map(|line| output::Target { cart_line: Some(output::CartLineTarget { id: line.id.clone(), quantity: None, }), ..Default::default() }) .collect(); Ok(output::CartLinesDiscountsGenerateRunResult { operations: vec![output::Operation { product_discounts_add: Some(output::ProductDiscountsAddOperation { candidates: vec![output::ProductDiscountCandidate { targets, value: output::ProductDiscountCandidateValue { percentage: Some(output::Percentage { value: dec!(15) }), ..Default::default() }, message: Some("Tier Gold discount".to_string()), ..Default::default() }], selection_strategy: output::ProductDiscountSelectionStrategy::First, ..Default::default() }), ..Default::default() }], }) }

Shipping Scripts hid or renamed shipping methods. The Function equivalent is a delivery_customization Function that takes the cart’s delivery options and returns a list of operations to hide or rename them.

Original Script (hide overnight shipping for heavy carts):

if Input.cart.subtotal_price_was > 50.0 && Input.cart.total_weight > 5000 Input.shipping_rates.delete_if do |rate| rate.name.include?("Overnight") end end Output.shipping_rates = Input.shipping_rates

The Delivery Customization Function input (input.graphql):

query Input { cart { cost { subtotalAmount { amount } } deliveryGroups { deliveryOptions { handle title } } lines { quantity merchandise { ... on ProductVariant { weight } } } } }

And the Function body (JavaScript example, since shipping rules are usually simple enough):

export function run(input) { const subtotal = parseFloat(input.cart.cost.subtotalAmount.amount); const totalWeight = input.cart.lines.reduce( (sum, line) => sum + (line.merchandise.weight || 0) * line.quantity, 0 ); if (subtotal <= 50 || totalWeight <= 5000) { return { operations: [] }; } const overnight = input.cart.deliveryGroups .flatMap((g) => g.deliveryOptions) .filter((o) => o.title.toLowerCase().includes("overnight")); return { operations: overnight.map((option) => ({ hide: { deliveryOptionHandle: option.handle }, })), }; }

The Function deploys the same way (shopify app deploy) and attaches in the admin under Settings > Shipping and delivery > Customizations.

If your store also has legacy checkout.liquid with custom shopify checkout scripts pulling third-party data, doing tax-ID validation, or rendering a custom banner, that is a different migration entirely. Checkout Extensibility replaces the entire checkout.liquid surface with a React-based extension system.

The shopify checkout scripts equivalent in Extensibility is a Checkout UI extension:

shopify app generate extension --type=checkout_ui_extension --name=tax-id-validator

This scaffolds a directory with a React component and a TOML manifest. The component declares its extension target (e.g. purchase.checkout.delivery-address.render-after), receives the checkout state via hooks, and renders UI into the checkout flow.

import { reactExtension, useApplyAttributeChange, BlockStack, TextField, Banner, } from "@shopify/ui-extensions-react/checkout"; export default reactExtension( "purchase.checkout.delivery-address.render-after", () => <TaxIdValidator /> ); function TaxIdValidator() { const applyAttributeChange = useApplyAttributeChange(); // ... validate against tax-ID service, set checkout attribute, render Banner }

The shopify scripts api had no formal test harness. Most teams tested in the admin by adding a test product to a cart with a test customer.

Functions support unit tests via the CLI:

cd extensions/tier-discount shopify app function test

The CLI runs your Function against fixture inputs (JSON) and compares to fixture outputs. You write the fixtures alongside the Function.

Real test matrix we use on Plus migrations:

Order of operations matters. We have seen merchants get this wrong and lose 24 hours of double-discounted orders.

1. Deploy the Function to production via shopify app deploy.
2. Install the app on the production store. Confirm the Function appears in the admin under the appropriate surface (Discounts > Functions, Shipping > Customizations, Payments > Customizations).
3. Attach the Function (e.g. create an automatic discount that uses it).
4. Run a real-customer test on production. Tagged test customer places a small order, confirm the math.
5. Verify in finance: the order export, the daily revenue summary, the customer’s email receipt all show the discount correctly.
6. Only after all of the above: disable the legacy Script in Plus admin > Apps > Shopify Scripts.
7. Re-verify the real-customer test. Same order math.

This is the silent-failure pattern from the previous post, restated more specifically. Functions exist as code inside an app. They do not run unless something in the admin says “use this Function.” A deployed Function with no discount automation, no shipping rule, no payment rule pointing at it is just bytecode sitting in S3.

Scripts could apply discounts arbitrarily. Functions return operations that Shopify merges. If three Discount Functions all target the same line, the merger applies them according to documented rules: by default, the largest discount wins per line, and the selectionStrategy: ALL operations can stack additively. Migrating multiple stacked Scripts to multiple stacked Functions can change the final price. Test every combination.

Scripts could read Input.cart.customer.tags directly. Functions access tags via the GraphQL input, but the input has to be configured to include them. Defaults vary by Function type. Always check your input.graphql includes the tag query (customer { hasTag(tag: "...") } or customer { metafields { ... } }) before assuming the data is available.

There is a 30-to-60-second propagation delay between shopify app deploy completing and the Function being visible in the admin’s automation picker. Do not race the deploy. Wait, refresh, attach.

Shopify Functions run inside a sandbox with hard CPU and memory limits, and they fail closed when you exceed them. This is a real production constraint that the Shopify Scripts API did not enforce visibly. We have shipped Functions to stores where the first production cart with 80 line items triggered a CPU-limit failure, dropped the discount, and the customer checked out at full price. That is a worse failure mode than a slow Script; with Scripts you might notice latency, with Functions you silently lose the discount.

The practical limits as of 2026: Functions get roughly 11 million instructions per invocation and need to return in single-digit milliseconds against the worst-case cart. The exact figures move with Shopify’s runtime updates, so check the current docs before you ship. What matters is the order of magnitude: a Function that allocates large vectors, iterates over the full cart times the full product catalog, or does complex string parsing is on the wrong side of the limit.

Three situations where the migration target should not be a Function:

• You need network calls. Functions cannot make HTTP requests. If your Script called an external tax-ID validator, a fraud-score API, or a third-party loyalty system, that logic moves to a Checkout UI Extension (which can call your app’s backend), not a Function.
• You need persistent state between invocations. Functions are stateless. State for counters, accumulators, or session-like data lives on the customer’s metafields or in your app’s backend, not in the Function.
• The Script was already at the Plus checkout scripts edge layer. If you were using Plus Checkout Scripts (the deeper customization layer that piped through additional_checkout_scripts), the migration is to Checkout Extensibility, not Functions. Most teams discover this when they try to migrate UI customizations into a Discount Function and find no UI surface there.

If you would rather not do this yourself, the Shopify Teardown is built for exactly this scope: 30 calendar days, fixed price, find $75,000/year in recoverable revenue or refund. The first 10 days are the audit and the migration plan. Days 11 to 30 are the actual Function port, Checkout Extensibility migration where needed, test matrix, and cutover.