If you are running a Shopify Plus store in 2026, you likely rely on Shopify Scripts (Ruby) for your complex tiered pricing, bundles, or shipping logic. But the writing is on the wall: Scripts are legacy technology. The future belongs to Shopify Functions (Wasm). This comprehensive guide covers everything you need to know about migrating, including architecture differences, code examples, debugging strategies, and real-world implementation patterns.

This is not just a syntax change. It is a fundamental architecture shift from "scripting on the fly" to "deployed compiled logic." It affects how you develop, test, and deploy customization logic across your entire checkout experience.

1. What Are Shopify Scripts? (The Legacy System)

Shopify Scripts were introduced as a Shopify Plus exclusive feature that allowed merchants to write custom Ruby code to modify cart behavior, shipping options, and payment gateways at checkout. The three types of Scripts available were:

• Line Item Scripts: Modify cart contents, apply discounts to specific products, create BOGO offers, tier pricing, and bundle discounts.
• Shipping Scripts: Hide, rename, or reorder shipping methods. Apply free shipping conditionally. Set minimum order values for specific shipping options.
• Payment Scripts: Hide or rename payment gateways based on customer tags, cart total, or product properties. Useful for B2B scenarios.

How Scripts Worked Technically

When a customer reached checkout, Shopify would execute your Ruby code in a sandboxed mruby environment. The script received an "Input" object containing cart data and returned a modified "Output" object. This happened synchronously, which meant:

• Complex scripts added latency to checkout
• CPU and memory limits could cause scripts to fail silently
• No way to unit test scripts outside of production
• Version control was difficult (copy-pasting into an editor)

While this code looks simple, the underlying infrastructure was becoming a liability. Every time Shopify wanted to improve checkout (like the new one-page checkout), they had to ensure backward compatibility with thousands of custom Ruby scripts. This slowed innovation.

2. What Are Shopify Functions? (The New Standard)

Shopify Functions are the replacement for Scripts. Instead of writing Ruby code in a web editor, you write code locally (in Rust or JavaScript), compile it to WebAssembly (Wasm), and deploy it as part of a Shopify App. The function is then "installed" on your store and runs at specific extension points.

Key Characteristics of Functions

• Compiled, Not Interpreted: Functions are pre-compiled to Wasm. This means execution is near-instantaneous (single-digit milliseconds).
• App-Based: A Function lives inside a Shopify App. You deploy the app to your store. The app can contain multiple functions for different purposes.
• Type-Safe: Both Rust and the JavaScript tooling (Javy) provide strong typing. Errors are caught at compile time, not runtime.
• Configurable by Merchants: Unlike hardcoded Script variables, Functions can expose Metafields that merchants edit in the Shopify Admin without touching code.
• Testable: You can write unit tests locally. You can simulate input payloads. You can CI/CD your discount logic.

The Conceptual Model

Think of Functions as "microservices for checkout logic." Each Function has a specific job:

1. It receives a structured JSON input (cart data, customer data, etc.)
2. It processes this input according to your business logic
3. It returns a structured JSON output (discounts to apply, shipping methods to hide, etc.)

Shopify's infrastructure handles calling your Function at the right moment, passing the right data, and applying the returned output.

3. The Architecture Shift: Ruby vs. WebAssembly

Understanding the architectural differences is crucial for a successful migration. This is not just a language swap; it's a paradigm change.

Legacy Architecture (Scripts)

1. Merchant writes Ruby code in the Script Editor app (browser-based)
2. Code is stored as text in Shopify's database
3. At checkout, Shopify spins up a sandboxed mruby interpreter
4. The interpreter parses and executes the Ruby code
5. Results are applied to the cart

Problems: Interpretation adds latency. Sandboxing is complex and limits capabilities. No external API calls allowed. No way to share logic between scripts.

New Architecture (Functions)

1. Developer writes code in Rust or JavaScript locally
2. Code is compiled to WebAssembly (a binary format)
3. The Wasm binary is deployed to Shopify via an App
4. At checkout, Shopify calls the pre-compiled Wasm binary
5. Execution happens in microseconds
6. Results are returned and applied

Benefits: Near-zero latency (5ms or less). Portable and secure by design. Functions can be versioned, tested, and deployed via CI/CD. Merchant-facing configuration via Metafields.

4. Complete Feature Comparison Table

Here is an exhaustive comparison between the two systems as of January 2026:

5. Types of Shopify Functions Available

Shopify Functions are not monolithic. Different "APIs" exist for different customization points. Understanding which API to use is critical for your migration.

5.1 Product Discount API

Replaces Line Item Scripts for product-level discounts. Applies percentage or fixed discounts to specific products or variants based on conditions you define.

• Use for: BOGO, tiered quantity discounts, category sales
• Input: Cart lines, product metafields, customer
• Output: List of discounts with targets

5.2 Order Discount API

Applies discounts at the order level (not per-line). Think "Spend $100, get 10% off your order."

• Use for: Threshold-based order discounts, loyalty discounts
• Input: Cart total, customer tags
• Output: Discount percentage or fixed amount

5.3 Delivery Customization API

Replaces Shipping Scripts. Hides, renames, or reorders shipping methods shown to the customer.

• Use for: Hiding expedited shipping below $50, renaming "Ground" to "Eco-Friendly", sorting cheapest first
• Input: Delivery options from carriers, cart data
• Output: Modified delivery options list

5.4 Payment Customization API

Replaces Payment Scripts. Hides or renames payment methods at checkout.

• Use for: Hiding COD for high-value orders, restricting PayPal for specific countries
• Input: Payment methods, cart, customer location
• Output: Modified payment methods list

5.5 Cart Transform API

A newer API that allows modifying cart lines before checkout. Useful for bundling, automatic add-ons, and cart splitting.

• Use for: "Add free gift over $100", split subscription items, bundle components
• Input: Cart lines
• Output: Cart operations (merge, expand, update)

5.6 Fulfillment Constraints API

Allows you to set constraints on how orders can be fulfilled. Useful for pickup-only items or location-restricted products.

6. Code Comparison: Script vs. Function Examples

Let's look at multiple real-world examples translated from Scripts to Functions.

Example 1: Spend $100, Get 10% Off (Order Discount)

Legacy Script (Ruby)

Shopify Function (JavaScript)

Key Difference: The Function returns a structured object. Shopify interprets this object and applies the discount. You don't mutate the cart directly.

Example 2: VIP Customer Discount (Product Discount)

Legacy Script (Ruby)

Shopify Function (Rust)

Complexity Note: The Rust version is more verbose because it's type-safe. Every field is explicitly handled. This makes errors obvious at compile time, but requires more upfront work.

Example 3: Hide Shipping Method Below Threshold

Legacy Script (Ruby)

Shopify Function (JavaScript)

7. Rust vs. JavaScript: Which Should You Choose?

This is the question I get asked most frequently. The answer depends on your team and use case.

My Recommendation: For 90% of Plus merchants, JavaScript (via Javy) is sufficient and significantly faster to develop. Rust is overkill unless you're an agency building reusable app components or handling extreme scale.

8. Comprehensive Pros & Cons Analysis

Advantages of Migrating to Functions

1. Future-Proofing: Functions are the only path forward. Scripts will eventually stop working. The longer you wait, the more urgent (and expensive) the migration becomes.
2. Performance: Wasm execution is 10-100x faster than interpreted Ruby. This directly impacts checkout speed and conversion rate.
3. Testability: You can write unit tests for your discount logic. You can run them in CI. You can catch bugs before they cost you money.
4. Version Control: Your function code lives in Git. You can track changes, roll back, and collaborate with a team properly.
5. Merchant Empowerment: Expose configuration (discount percentages, thresholds) via Metafields. Marketing can tweak promos without a developer.
6. Access to New Features: Checkout Extensibility features (like UI Extensions, branding APIs, post-purchase offers) only work with Functions.

Disadvantages and Challenges

1. Learning Curve: If your team only knows Ruby, learning Rust is non-trivial. JavaScript is easier but still requires understanding the Shopify Functions framework.
2. Setup Overhead: You need a Partner Dashboard app, Shopify CLI installed, local environment configured. This is more work than copy-pasting into a web editor.
3. Debugging: Logs appear in the Partner Dashboard, not inline with your store. Correlating errors to specific checkouts can be tricky.
4. App Management: Your function is part of an App. If you have many Functions, you need to manage them as an app portfolio, not loose scripts.
5. No Direct Cart Mutation: You can't "just change the price" like in Scripts. You return instructions, and Shopify applies them. This requires a mental model shift.

9. Real-World Use Cases and Implementation Patterns

10. Step-by-Step Migration Plan

Here is the comprehensive migration process I follow with Plus merchants:

Phase 1: Discovery & Audit (1-2 Days)

1. Export all active Scripts from the Script Editor
2. Document what each script does in plain English
3. Categorize: Discount (Line Item/Order), Shipping, Payment
4. Identify interdependencies (e.g., "Script A and Script B both affect the same product line")
5. Note any dynamic values (thresholds, percentages) that should become Metafields

Phase 2: Environment Setup (1 Day)

1. Install Shopify CLI 3.x on your development machine
2. Create a new App in Partner Dashboard (Development App is fine for single-store)
3. Scaffold a Function project: shopify app generate extension
4. Connect to your development store
5. Run shopify app dev to verify the connection

Phase 3: Development (3-10 Days per Function)

1. For each Script, create a corresponding Function of the appropriate type
2. Write the input query (GraphQL) to fetch needed data (cart lines, customer tags, metafields)
3. Implement the business logic in your chosen language
4. Write unit tests with sample input payloads
5. Test locally using shopify app function run

Phase 4: Deployment & Activation (1 Day)

1. Deploy the app: shopify app deploy
2. In Shopify Admin, go to Settings > Apps > [Your App] > Install
3. For Discount Functions: Create a new Discount using your Function as the type
4. For Shipping/Payment Functions: Activate in the Checkout Settings
5. Configure any Metafields exposed by your Function

Phase 5: Parallel Testing (1-2 Weeks)

1. Run both old Scripts and new Functions simultaneously (if possible)
2. Compare discounts/behavior on test orders
3. Monitor error logs in Partner Dashboard
4. Fix any discrepancies

Phase 6: Cutover & Decommission (1 Day)

1. Disable old Scripts in the Script Editor
2. Confirm Functions are handling all logic
3. Document the new architecture for your team
4. Celebrate!

11. Debugging and Testing Strategies

Local Testing

The Shopify CLI provides a shopify app function run command that lets you test your function locally with a JSON input file.

Run: cat input.json | shopify app function run

Output will be the JSON your function returns. Compare it to expected output.

Unit Testing with Jest (JavaScript)

Production Debugging

Function errors appear in the Partner Dashboard under your App > Extensions > [Function] > Logs. Use console.error() (JS) or eprintln!() (Rust) to log debug information.

12. Performance Benchmarks and Optimization

In production environments, I have measured the following execution times:

Optimization Tips:

• Minimize the data requested in your input query. Only fetch fields you actually use.
• Avoid deeply nested loops. Flatten logic where possible.
• For Rust: Use iterators instead of manual loops for better compiler optimization.
• For JavaScript: Avoid JSON.parse() on large objects inside the function.

13. Common Migration Mistakes to Avoid

1. Trying to Migrate All Scripts at Once: Start with one script. Get comfortable with the workflow. Then tackle the rest.
2. Ignoring Discount Stacking: In Scripts, you manually controlled stacking. With Functions, Shopify's "Discount Combinations" settings manage this. Configure them correctly or discounts may stack unexpectedly.
3. Hardcoding Values: The whole point of Functions is configurability. Use Metafields for thresholds, percentages, and product exclusions.
4. Skipping Unit Tests: You finally have the ability to test. Use it. Discount bugs are expensive.
5. Not Monitoring Logs: After deployment, watch the Partner Dashboard logs for the first few days. Edge cases will surface.
6. Forgetting About B2B: If you have B2B catalogs or customer-specific pricing, ensure your Function queries handle company context.

14. Frequently Asked Questions (15+ FAQs)

15. Conclusion and Next Steps

Migrating from Shopify Scripts to Shopify Functions is not optional for Plus merchants who want access to modern checkout features. The longer you wait, the more technical debt you accumulate and the more urgent the migration becomes.

Here is your action plan:

1. Audit your current Scripts today. Document what they do.
2. Set up a local development environment with Shopify CLI.
3. Start with your simplest Script. Migrate it as a learning exercise.
4. Write tests. You finally can. Don't skip this step.
5. Deploy to a development store first. Test thoroughly.
6. Roll out to production with parallel testing.
7. Monitor logs for the first week. Fix edge cases.