Shopify Functions

Functions do not run all at once. Each API runs at a fixed point of the cart and checkout flow and reads what the earlier points produced, which is why a validation cannot see a cart that has not been discounted yet and why a discount sees the lines after a cart transform changed them.

Source: Shopify: Function APIs, function execution order in checkout

The stages of the figure, in order, are the cart lines (Cart Transform), the cart line discounts (Discount), the fulfillment groups (Fulfillment Constraints and Order Routing), the delivery methods (the pickup generators, then Delivery Customization), the delivery discounts (Discount again, for the shipping class), the payment methods (Payment Customization) and finally the verification (Cart and Checkout Validation). Two practical consequences follow. A delivery customization runs before the delivery discounts of stage 5, and a payment customization runs after every discount has been calculated. When the order of two Functions matters, check the stage rather than assuming that the one installed first runs first.

Each API page lists the Shopify surfaces on which it runs. The entries that decide whether a rule will apply are worth knowing before designing a Function. "Partly" means the API page states a restriction, summarised below the table.

Source: Shopify: Discount Function API, Cart Transform, Delivery Customization, Payment Customization and Cart and Checkout Validation, compatibility lists read on 2026-10-27.

The restrictions behind "Partly" are the following. A Discount function is not supported with network access on draft orders, is not re-run when an order is edited in checkout, and is not re-run when recurring orders are created (a shipping discount on the original order becomes a 100 percent shipping discount on the recurring orders, whatever its value). Cart Transform in checkout rejects lineExpand, linesMerge and lineUpdate when a selling plan is present, and on POS it needs ProductVariant.requiresComponents to be true for full support. Delivery Customization works on POS only when shipping to a store. Payment Customization on accelerated checkout is limited as described in the payment section.

For Pocket Coffee the table has one immediate effect: the Coffee Club discount works at a POS counter (a market stall is a realistic extension of the shop), while the parcel-weight validation does not, so a weight check for POS orders would need another mechanism. It also means that nothing in delivery-rules or payment-rules can influence the cart page, where the buyer has not yet chosen a destination.

The configuration of the first extension, exactly as it was built.

Source: Shopify: Function APIs, configuration

Every key that the file accepts is listed below.

Source: Shopify: Function APIs, configuration and Shopify: Metafields for input queries

The export value is a kebab-case string in the JavaScript templates (cart-lines-discounts-generate-run) and the exported JavaScript function has the camelCase spelling (cartLinesDiscountsGenerateRun); the CLI generates the Wasm exports from the targets of the configuration. In Rust the export is the name of the function marked with #[shopify_function], in snake case (cart_lines_discounts_generate_run), so the export values differ between the two languages. For API versions up to 2023-07 the CLI still compiles JavaScript to a single _start export for backward compatibility.

The codegen key of the extension package.json tells shopify app function typegen which schema and queries to read and where to write the TypeScript types, which JavaScript projects use through JSDoc.

Source: Shopify/extensions-templates, folder functions-discount-js

shopify app function typegen generated generated/api.ts (3,488 lines for the Discount schema) from the schema and from the queries in src/. It names every operation after the query: the query CartLinesInput produced the type CartLinesInput, whose field discount.metafield.jsonValue is typed unknown, because the content of a JSON metafield is not known to GraphQL. The generated file also declares enums such as DiscountClass and ProductDiscountSelectionStrategy, which the examples below import. The build runs typegen itself, so running it by hand is only needed to refresh editor types.

The extensions sit in an app whose shopify.app.toml declares the scopes needed by the mutations that activate them.

Source: Shopify: App configuration (shopify.app.toml) and Shopify: Access scopes

The client id is a placeholder of 32 zeros and the URLs use the reserved .invalid top-level domain, so the file can be built but not deployed. The scopes follow the access scopes reference: write_discounts for the discount mutations, write_cart_transforms, write_delivery_customizations, write_payment_customizations and write_validations for the four owners of the other APIs.

Each API exposes an Input type. The parts that recur are cart (lines, merchandise, buyer identity, delivery groups, cost, attributes), localization (country, language), shop (local time, metafields, app-owned metaobjects), presentmentCurrencyRate (to convert amounts from the shop currency), fetchResult (the answer of the fetch target when there is one), and the function owner under a name that depends on the API: discount, cartTransform, deliveryCustomization, paymentCustomization or validation. Each owner exposes metafield(namespace:, key:), which is how a merchant’s configuration reaches the code. Cart lines are a union: the merchandise is a ProductVariant or a CustomProduct, so queries select __typename and use inline fragments, and JavaScript tests it before reading variant fields.

The Discount API adds enteredDiscountCodes and triggeringDiscountCode; Payment Customization adds the list paymentMethods (with id, name and placements); Cart and Checkout Validation adds buyerJourney.step, so that a rule can be applied only at, for example, the completion of checkout.

Shopify computes the cost of an input query from its text, before running the Function, and rejects the query when the cost is above 30 or its text is longer than 3,000 bytes (comments are not counted).

Source: Shopify: Function APIs, input query limits

Container fields (such as cart or lines) cost nothing and each selected field is counted once, however many lines the cart has. Aliasing a costly field several times charges it each time, so ten aliases of hasAnyTag cost 30, the whole budget. List arguments and variables are limited to 100 elements and metafield values larger than 10,000 bytes are not returned. A query over budget fails validation with Query has complexity of <cost>, which exceeds max complexity of 30.

Because the check happens at deploy time, a small script is useful during development. This one applies the table with graphql 16 to any query file and a schema; it reproduces the cost of 8 that Shopify documents for its own example.

Source: Shopify: Function APIs, input query limits. The script is original; it implements the cost table above and nothing else.

Run on the queries of this page, the script printed these costs, and it printed 8 for the documented example and 33 for a query with eleven aliased hasAnyTag selections.

Source: Shopify: Function APIs, input query limits

The local tools do not enforce the limit: shopify app build accepted the query with a cost of 33, and app function run does not read the query at all. The error comes from Shopify’s own validation, so the script above is the way to see it before a release.

Hard-coding a percentage in the code means a new release for every promotion. The documented pattern is to keep the configuration in a metafield on the function owner and to read it in the input query.

Input query variables go one step further: values that are arguments of fields, such as the tag in hasAnyTag(tags: [$memberTag]), cannot come from the jsonValue of a metafield read in the same query, because the argument must be known before the query runs. A query declares variables with defaults, and the target’s input_variables points at the JSON metafield that overrides them. Pocket Coffee uses this so that the tag names are configuration instead of constants:

Source: Shopify: Use variables in input queries

The aliases isMember and isBeans keep the JavaScript readable, and each hasAnyTag costs 3, which is part of the 11 points counted above. hasAnyTag returns one boolean, which is cheaper to process than receiving all the tags and searching them in the module. Other fields that do the filtering inside Shopify are hasTags, inAnyCollection and inCollections.

The input query reads Shopify data on behalf of the app, so the fields it selects are bound to access scopes. Customer details and addresses additionally need protected customer data approval. Both matter in production: the Dev Dashboard shows the input and output of a Function run only when the app has the scopes that the input query requires (since 2026-05-13 these logs are visible automatically instead of through merchant-shared logs), and lists the missing scopes when a run cannot be shown.

Source: Shopify: Discount Function API

The operation groups share a selection strategy that tells Shopify how to pick among the candidates.

Source: Shopify: Discount Function API and the schema file of the discount template

A candidate carries a message (shown to the buyer), targets, a value and optional fields. The value is either a percentage or a fixedAmount (a product candidate’s fixed amount has appliesToEachItem). Order candidates take conditions (cartLineMinimumQuantity, cartLineMinimumSubtotal or orderMinimumSubtotal), and product candidates take prerequisites, a list of cartLine ids with the required quantity, which is how a "buy X, get Y" discount is expressed (added to the API in 2026-04). associatedDiscountCode ties a candidate to an entered code and is meant for functions with network access.

For a code discount, triggeringDiscountCode holds the code that started the Function, and enteredDiscountCodes lists every code the buyer typed. A function with network access may validate external codes with enteredDiscountCodesAccept, which must contain a subset of the entered codes. Since 2025-12-17, any Discount function that is backed by an automatic discount can reject codes with enteredDiscountCodesReject, giving a custom message, to stop double discounting on sale prices or to disqualify products; only codes whose rejectable flag is true can be rejected. Shopify validates a result and raises an error when it breaks one of these rules: more than one operation of the same kind, an accepted code that was not entered, a rejected code that was not entered or is not rejectable, or an associatedDiscountCode that was not entered.

The Pocket Coffee rule is: a customer of the Coffee Club segment gets 10 percent off the beans. The merchant tags the members coffee-club and tags the bean products beans; the percentage lives in a JSON metafield. The input query is the one shown before; the logic returns early whenever there is nothing to do, because each instruction costs checkout time.

Source: Shopify: Build a discount function and the JavaScript discount template of Shopify/extensions-templates

Three details of this code are worth reading closely. The discountClasses test returns early when the merchant did not enable the product class. The test on merchandise.__typename guards the union before the variant’s product is read. And the message is what the buyer sees next to the discounted line, so it is written for the buyer, not for the log.

The same extension implements the shipping side: members get free shipping when the subtotal reaches 40 EUR.

Source: Shopify: Discount Function API, delivery run target

Source: Shopify: Discount Function API, delivery run target

The subtotal arrives as a decimal string ("45.00"), which the code converts with Number. Money is exposed as a Decimal scalar so that no precision is lost in transit; converting to a number is acceptable for a threshold comparison, and an amount that must be exact in the output is better returned as it was received. A checkout can hold several delivery groups (shipping and pickup, for example), so the candidates are created for every group instead of assuming one.

src/index.js re-exports both functions, which is how one module serves two targets.

Source: Shopify/extensions-templates, folder functions-discount-js

shopify app function run executes the compiled module with an input that you supply, with the same runner (function-runner 9.2.2) that the CLI bundles. The first input is a member whose cart holds one bean line and one equipment line.

Source: Shopify: Test and debug Shopify Functions

Source: Shopify CLI: app function run

The --input path must be absolute (relative paths are resolved from the extension folder), and --export is needed when the module has more than one target. The command printed the input, the logs (empty) and this output, followed by the measurements:

Source: Shopify: Test and debug Shopify Functions. Output of the local run on 2026-10-27; only the bean line (id 1) is discounted.

Source: Shopify CLI: app function run

The early return is visible in the numbers: the guest run executes about 130,000 fewer instructions than the member run. Even the guest run costs 198,000 instructions, which is the cost of starting the JavaScript engine and reading the input; that fixed cost is what a Rust Function does not pay, as discussed in the performance section.

The function owner is created with an Admin API mutation. Since the 2025-10 API version the mutations identify the function by the handle that you defined in shopify.extension.toml (functionHandle), which is stable across environments, instead of the functionId, which changes at every deploy. The mutation also sets the discount classes, the combination rules and the two metafields that the input queries read: the configuration of the Function and the variables of the input queries.

Source: Shopify: discountAutomaticAppCreate. Validated against the Admin GraphQL 2026-10 schema; not executed, because it needs a store.

A merchant can create the same discount in the admin, in the Discounts page, by choosing the discount type that the app provides; the [extensions.ui] or [extensions.ui.paths] configuration decides which screen the merchant sees, and discountCodeAppCreate creates the code variant. The app can list its own Functions, with their ids, titles and API types, with the shopifyFunctions query.

Rust is the language Shopify recommends for Functions that run on large carts or that are computationally complex. The current template produces this code for the lines target (unmodified from the functions-discount-rs template; it applies the 10 percent order discount and the 20 percent product discount of the template, not the Pocket Coffee rule).

Source: Shopify/extensions-templates, folder functions-discount-rs (the product class branch of the template is omitted here for brevity). This code was not compiled, because no Rust toolchain was installed for this page.

The code is typed against the schema through the schema module, whose types the #[typegen] macro in src/main.rs generates from schema.graphql and the input query.

Source: Shopify/extensions-templates, folder functions-discount-rs

The build configuration changes from the JavaScript one in the export values and in [extensions.build].

Source: Shopify: Rust for Functions

The Product Discount, Order Discount and Shipping Discount APIs are deprecated since API version 2025-04 and Shopify asked developers to move before API version 2026-04. Their targets (purchase.product-discount.run, purchase.order-discount.run, purchase.shipping-discount.run) are replaced by the two targets above. The changes the migration guide lists are these.

Source: Shopify: Discount Function API, migrate from deprecated Discount Function APIs and Shopify changelog: deprecation of Product, Order and Shipping Discount Function APIs (2025-05-21). The old target names are those of the deprecated templates in the catalogue (order_discounts still uses purchase.order-discount.run).

Source: Shopify: Cart Transform Function API

When operations target the same line, Shopify orders them by activation time and applies these rules.

Shopify rejects lineExpand, linesMerge and lineUpdate for a cart that has a selling plan, which is a rejection, not an error. Other invalid cases are a component quantity below zero, a line that does not exist, a variant id that does not exist, a negative price, a merge quantity larger than the line’s quantity, and an update that targets a line that is being expanded or merged.

For a linesMerge the adjustment is applied to the sum of the component prices; for a lineExpand it is applied to the price of the bundle product. When a lineExpand gives no fixed price per unit, Shopify allocates the bundle price to the components by weight, where the weight of a component is its unit price multiplied by its quantity. For a bundle price of 100 and components of 10 times 1, 20 times 2 and 30 times 3, the weights are 10, 40 and 90 (total 140) and the shares are 7.14, 28.57 and 64.29, which is the worked example in the API reference. The amounts the input shows are in the presentment currency, and output prices are interpreted in that currency too; to start from a shop-currency amount, select presentmentCurrencyRate in the input and convert before returning the price.

Title and image overrides must use images uploaded to the Shopify CDN (an image URL from another host fails with invalid_image_url) and without a size suffix; the override shows in the cart, checkout and order notification emails, but a theme must print item.title (cart) or line.title (notification) to display the new title.

The API reference lists error codes per operation. Among them, exceeded_maximum_number_of_supported_expanded_cart_items (more than 150), expanded_items_missing_prices (some components priced, some not), cannot_combine_price_adjustment_and_price_per_component, component_merchandise_not_found, insufficient_component_quantity_to_merge, parent_variant_not_found, invalid_image_url, image_not_found, fixed_price_adjustment_cannot_be_negative and update_feature_not_available (the shop is not on Plus or a development store) are the ones that appear while building. A runtime failure of a cart transform is exposed by the Storefront API, since API version 2026-04, as the cart error code MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR instead of the generic INVALID error with the message "An error occurred in your cart". blockOnFailure of cartTransformCreate decides whether a failed run blocks cart and checkout operations.

The Pocket Coffee Starter kit is one variant (SKU PC-KIT-001) that contains the hand grinder and 250 g of beans. The merchant sells it as one line, and the cart transform expands it into its two components, so that stock is decremented for the real variants and the cart shows what the buyer gets. The components are configuration, stored in a JSON metafield on the cart transform, not in the code.

Source: Shopify: Add a customized bundle function

Source: Shopify: Add a customized bundle function

The expansion gives no component prices, so Shopify allocates the bundle’s price by weight as described above. The title Starter kit keeps the bundle’s name on the expanded line. The input of the local run holds the kit and two bags of beans:

Source: Shopify: Test and debug Shopify Functions

and the output is a single lineExpand for the kit line; the bags are left alone.

Source: Shopify: Test and debug Shopify Functions. Output of the local run on 2026-10-27: 254,531 instructions, 1,995 bytes of Wasm.

Creating the owner, with the configuration metafield, needs one mutation; the two variant ids are placeholders.

Source: Shopify: cartTransformCreate. Validated against the Admin GraphQL 2026-10 schema; not executed.

An operation names an option by its handle. Matching on the title is tempting and is what the example below does for readability, but it is brittle: a merchant can rename an option, a translation changes the title, and two options can share a pattern. Since API version 2026-10 a delivery option also exposes its metafields (metafield(namespace:, key:)), which lets a function that generates options, such as a carrier app, write a typed value that a delivery customization reads by name instead of parsing the title. Metafields of a delivery option are not persisted after checkout.

Pocket Coffee offers a same-day courier called "Same-day Madrid", only valid for postal codes that begin with 28, and a "Standard" option for everything else. The function hides the same-day option elsewhere and renames "Standard" to state the delivery time.

Source: Shopify: Build a delivery options function

Source: Shopify: Build a delivery options function

Run with a Barcelona address (08001), the function renames the standard option and hides the Madrid one:

Source: Shopify: Test and debug Shopify Functions. Output of the local run on 2026-10-27: 199,405 instructions, 2,146 bytes of Wasm. The input is extensions/delivery-rules/tests/barcelona.json.

Activation uses deliveryCustomizationCreate:

Source: Shopify: deliveryCustomizationCreate. Validated against the Admin GraphQL 2026-10 schema; not executed.

Pocket Coffee sells cash on delivery only in Spain (the courier handles the cash), and wants the bank transfer method to say that the parcel ships after the payment arrives.

Source: Shopify: Create a payments function

Source: Shopify: Create a payments function

For a German buyer (DE) the local run hides the cash method and renames the bank transfer, and leaves the card alone:

Source: Shopify: Test and debug Shopify Functions. Output of the local run on 2026-10-27: 185,909 instructions, 1,907 bytes of Wasm. The input is extensions/payment-rules/tests/germany.json.

The owner is created with paymentCustomizationCreate.

Source: Shopify: paymentCustomizationCreate. Validated against the Admin GraphQL 2026-10 schema; not executed.

Pocket Coffee ships in parcels of at most 5 kg. The function sums the weight of the lines (each variant has a weight and a unit) and adds an error on the cart when the total is above the limit.

Source: Shopify: Create a server-side validation function

Source: Shopify: Create a server-side validation function

A cart with four 1 kg bags and five 250 g bags weighs 5.25 kg:

Source: Shopify: Test and debug Shopify Functions. Output of the local run on 2026-10-27 for extensions/parcel-limit/tests/heavy.json: 193,127 instructions, 2,123 bytes of Wasm. A cart of two 1 kg bags (light.json) returned {"validationAdd": {"errors": []}}.

The first version of the fixture used three 250 g bags (4.75 kg), which is under the limit, and correctly produced no error; the test case was changed to five bags to cross the limit. A boundary of exactly 5 kg passes, because the check is a strict greater-than.

Source: Shopify: validationCreate. Validated against the Admin GraphQL 2026-10 schema; not executed.

Shopify CLI compiles JavaScript with Javy, a build tool and a runtime engine. The module produced contains your code but not a JavaScript engine; it links to the engine at run time. That is why the five extensions of this page compile to modules between 1,907 and 3,345 bytes.

What the runtime provides and what it does not:

Both limits were reproduced. A function declared async produced the log Pending jobs in the event queue. Scheduling events is not supported when the event-loop runtime config is not enabled, a Wasm backtrace and the output {}. A call to fetch produced Error: fetch is not defined with a stack trace and the local runner’s Invalid Output error. Both cases are covered by the pitfalls list at the end of this page.

TypeScript works through the same esbuild step; the generated api.ts declares the input and result types, and the operation enums are imported from it as the templates do. The generated jsonValue type is unknown, so a TypeScript function casts the configuration to its own type. The Decimal scalar is typed as a string in the generated types, while the templates return numbers for percentages, which the schema accepts at run time.

The requirements are the latest stable Rust with the wasm32-unknown-unknown target installed (rustup target add wasm32-unknown-unknown), Shopify CLI 3.85.0 or newer and version 2.0.0 or newer of the shopify_function crate. The older wasm32-wasi and wasm32-wasip1 targets and the cargo-wasi tool are obsolete: Rust 1.84 removed wasm32-wasi, and crate 2.0.0 and newer builds with the unknown-unknown target. Functions generated by the CLI use the latest crate.

The crate has five parts.

Source: Shopify: Rust for Functions

A typical Cargo.toml keeps the release profile that makes the module small.

Source: Shopify/extensions-templates, folder functions-discount-rs; the package name is changed to the extension handle. A rust-toolchain.toml with channel = "stable", the components rustfmt and clippy and the target wasm32-unknown-unknown is part of the template.

Configuration read from a JSON metafield is typed with custom_scalar_overrides, which links the jsonValue field to your own struct, so that no JSON parsing appears in the code. The key is the path to the field, starting with the query’s operation name.

Source: Shopify: Rust for Functions, migrating from JavaScript. The two code fragments of the reference are combined here. Not compiled.

To keep a Rust module under 256 kB, the documentation recommends keeping the template profile, leaving wasm_opt enabled, using regex_lite instead of regex, using to_ascii_uppercase and to_ascii_lowercase to avoid Unicode tables, querying only the data that is needed (typegen produces code for every field of every query) and keeping JSON metafields small (deserialisation code grows with the struct). cargo doc --open and cargo expand show the generated types.

To move an existing JavaScript function to Rust, add the Rust files to the same extension: update the JavaScript to @shopify/shopify_function 2.0.0 or newer (the CLI picks its local runner from this version), add wasm32-unknown-unknown, generate a temporary Rust extension to copy Cargo.toml and the .rs files, delete the temporary folder, add target/ to .gitignore, add __typename to fragments on interfaces and unions in the input queries (this does not affect the JavaScript), port the logic, then switch the export values and the [extensions.build] section of the toml, keeping the JavaScript values as comments. Integration tests can run both builds by passing targeting[fixture.target].export to the runner, and the swap is reversible until the JavaScript source is removed.

The Shopify Wasm API is a small set of imported functions that a module uses to read input and write output lazily, so that no JSON parser needs to be embedded in the binary. Values are 64-bit NaN-boxed numbers whose tag says whether they are a null, a boolean, a number, a string, an object, an array or an error. A module must export, for each target, a function of type (func) with no parameters and no results, and it logs through the imported shopify_function_log_new_utf8_str; writes to standard error are ignored. Read errors (decode error, not an object, byte array out of bounds, read error, not an array, index out of bounds, not indexable) and write status codes (success, I/O error, expected key, object length error, value already written, not an object, value not finished, array length error, not an array) are numeric and may grow, so new codes must be handled. Moving from version 1 to version 2 of the Wasm API means importing from shopify_function_v2, no longer passing a context pointer, and removing the context creation and output finalisation calls.

Source: Shopify: WebAssembly for Functions. The WAT module is the reference’s skeleton of an export that matches the toml export = "run".

The Rust chapter WebAssembly with Rust explains the compiler targets and the Wasm model that Functions build on; Functions themselves use the first-party crate and not wasm-bindgen.

Source: Shopify CLI: app function run, app function replay and Shopify: Test and debug Shopify Functions. The first five rows and info were run; schema was run only to see its login message; dev, deploy and replay need a Shopify identity or a log file and were not run.

shopify app function info --json returned, for the discount extension:

Source: Shopify CLI: app function info. Output shortened; the absolute paths are replaced by placeholders.

Shopify CLI 5.0.0 removed shopify app logs and shopify app logs sources. Running the command now stops with this message:

Source: Shopify CLI: app commands. Message printed by Shopify CLI 5.0.0 on 2026-10-27.

The current Shopify guide on testing and debugging still describes the command with its --source option, so for CLI 5.0.0 and newer app dev and the Dev Dashboard are the sources of function logs.

console.log in JavaScript, log! in Rust and the imported shopify_function_log_new_utf8_str in other languages write to the function log, which is truncated after 1 kB and is shown by app function run under "Logs". Printing to standard output or standard error does not work as a debugging tool. Logging costs instructions even when the text is truncated, so temporary logs must be removed before deploy, and logs must never contain customer data. Because runs are deterministic, a detailed log can be added to a local build and a production run reproduced exactly with its input.

Every Function template ships tests/default.test.js and tests/fixtures/, powered by the package @shopify/shopify-function-test-helpers (1.1.0 at the check date, which also returns the instruction count of each run). The test builds the module, reads the function information from the CLI, validates the input query against the schema, validates each fixture’s input and expected output against the schema and the query, runs the compiled Wasm and compares the result with the fixture. A fixture is a JSON file with a payload that has export, target, input and output, and every .json file in the folder becomes a test.

Source: Shopify: Test and debug Shopify Functions, writing Wasm integration tests

The suites of the five extensions (nine tests: four for the discount, one each for the bundle, the delivery rules and the payment rules, two for the parcel limit) all passed with Vitest 3.2.7:

Source: Shopify: Test and debug Shopify Functions

The unmodified template test fails against Shopify CLI 5.0.0. The helper expects shopify app function info --json to return schemaPath, wasmPath, functionRunnerPath and an object targeting at the top level, but CLI 5.0.0 (which introduced typed JSON output for every command) returns the same information inside a function key and lists the targets as an array called targets. The first failure was Failed to build schema from undefined, and after unwrapping the key the next one was Cannot read properties of undefined (reading 'cart.lines.discounts.generate.run'). Until the helper or the templates are updated, the beforeAll of the test can adapt the shape.

Source: Shopify/shopify-function-test-helpers and the default.test.js of the functions-discount-js template. The adaptation is original and was run against Shopify CLI 5.0.0.

A pure unit test (Vitest for JavaScript, run_function_with_input and cargo test for Rust) is faster, can be step-debugged, and does not need the compiled module, but it does not execute in Wasm, so a rare difference between the test and production is possible. The Wasm integration test and app function run are the two checks that run the real binary.

The first extension was run on carts of 1, 50, 200 and 1,000 bean lines, all discounted by a member. The table shows the instructions of the JavaScript module and the limits that app function run printed for each input.

Source: Shopify: Optimize instruction counts. Measured on 2026-10-27 with shopify app function run; the input size limit printed was 125 kB for up to 200 lines and 625 kB for 1,000 lines, the output limit 19.53 kB and 97.66 kB.

A 200-line cart of beans, with the function doing one boolean check per line, used 69 percent of the 11 million allowed instructions, which is why Shopify warns that JavaScript functions meet the limit sooner. The cost is roughly linear: about 36,000 instructions per line in this function, on top of a fixed cost of about 270,000 instructions. A real function with a richer rule per line, or with a nested loop, would exceed the limit well before 200 lines. The chart also shows the shape of the limit: it grows at the same rate as the cart above 200 lines, so a function that is linear in the number of lines stays inside the allowance, and a quadratic one does not.

The local runner reports; it does not enforce. A test function with a busy loop reported 2,295,222,693 instructions against an allowance of 11 million and printed the output without any error, so a local run must be compared with the printed limit by hand (or by --json, whose instructions field is meant for scripts). In production, Shopify stops a function that exceeds the instruction limit and reports an InstructionCountLimitExceededError. Other failures observed locally:

Source: Shopify: JavaScript for Functions and Optimize instruction counts. The first two rows were produced on 2026-10-27 with modified copies of the discount extension that were deleted afterwards.

What a failed Function means for the buyer depends on the API: a Cart Transform run failure surfaces as the Storefront error code MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR and blocks the operation when blockOnFailure is set, and a Validation function with blockOnFailure set stops checkout. These are decisions to take at activation time.

Shopify lists the improvements in order of effect: migrate to Rust, request only the input the function needs, profile the function and optimise the hot paths, and track instruction counts in the tests so that they do not regress. For input, query only what is read, let Shopify evaluate conditions through hasAnyTag, inAnyCollection and similar fields, read JSON metafields with jsonValue, and precompute configuration when the merchant saves it so that the function receives the shape it needs (a lookup of ids rather than rules to evaluate). For logic, return early, avoid nested loops over lines (build a map or a set in one pass), avoid repeated work, avoid string work such as formatting and case conversion, and remove debug logging. For Rust, use the latest crate, borrow instead of cloning, avoid allocating strings inside loops, and try opt-level values other than "z" while watching the 256 kB limit.

To profile, build a Rust module with strip = false in [profile.release] and wasm_opt = false in [extensions.build], then run shopify app function run --input input.json --profile and open the .perf file in Speedscope. A JavaScript function shows every frame as unknown, because Javy modules carry no function names.

The Help Center describes the Script types and templates, and the Function API pages describe the use cases of each API; combining the two gives this mapping. A Script that has no row has no documented Function equivalent.

Source: Shopify Help Center: Shopify Scripts and the Script Editor app and the Function API references linked above

Source: Shopify changelog: Shopify Scripts will be deprecated on June 30, 2026. The flowchart is original, built from the mapping above.

A Script and its replacement differ in how they are made, tested and operated. The Script was edited and tested in the Script Editor, with its debugger, and published from the admin. A Function is source code in an app repository, built with the CLI, tested with fixtures and released with an app version; its configuration is data (metafields), not code; it can be written in several languages; and it is installed through an app, which makes the plan rules of the availability section the first thing to settle for a merchant that used to write its own Scripts.

The Coffee Club line item rule, as a Script and as a Function, shows the difference. The Script below is written in the style of the Script Editor templates and can no longer be run anywhere; it is shown only for comparison.

Source: Shopify Help Center: Shopify Scripts and the Script Editor app. Illustrative only: the Scripts API is retired, the snippet was not executed and its method names are reproduced from the Script Editor templates, whose reference could not be read for this page.

The Function differs in four visible ways. The Script changed prices itself (change_line_price); the Function asks Shopify to apply a discount, so reports and combination rules treat it as a discount. The tags and the percentage are constants in the Script and configuration in the Function. The Script ran in the cart object; the Function receives only the fields in its query. And the Script was a single file; the Function has an input query, an output type, a configuration and a test.