Migrating from Shopify Scripts to Shopify Functions

Functions availability

Users that have checkout.liquid customizations need to upgrade to Shopify Extensions in Checkout to use Function APIs.
Stores on any plan can use public apps that are distributed through the Shopify App Store and contain functions. Only stores on a Shopify Plus plan can use custom apps that contain Shopify Function APIs.
Some Shopify Functions capabilities are available only to stores on a Shopify Plus plan. See Shopify Function APIs for details.

Shopify Scripts allow you to customize cart behavior, shipping, and payment methods in a store. With Shopify Functions, these customizations are now handled through dedicated Function APIs that offer better performance and flexibility. This guide shows how to migrate your existing Shopify Scripts to Shopify Functions by testing in production without disrupting customers.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

Map your existing Shopify Scripts functionality to the right Shopify Functions.
Test new Functions safely alongside existing Scripts in production.
Deploy Functions without affecting customers.

Anchor to RequirementsRequirements

You have an existing Shopify Script that you want to migrate.
You have access to a development store for initial testing.
You're familiar with creating Shopify Functions using Shopify CLI.
You have the necessary permissions to use the Script Editor app in the target store.

Anchor to Function APIs mappingFunction APIs mapping

Use the following table to map your existing Shopify Script to the appropriate Function API:

Shopify Script type	Shopify Function API	Use case
Line item scripts	Discounts API	Apply discounts to products, or the entire cart.
Line item scripts	Cart Transform API	Modify cart line items (bundle, merge, or add items).
Line item scripts	Cart and Checkout Validation API	Validate cart contents and block checkout under certain conditions.
Shipping scripts	Delivery Customization API and Discounts API	Hide, rename, or reorder delivery methods, and apply discounts to delivery methods.
Payment scripts	Payment Customization API	Hide, rename, or reorder payment methods.

Anchor to Step 1: Create a preview link for your existing scriptStep 1: Create a preview link for your existing script

You can test your new Shopify Function alongside your existing Shopify Script without affecting customers.

In the Shopify admin, go to Apps > Script Editor.
Create a temporary script with the following code but don't publish it:

Output.cart = Input.cart
Save the script as a draft and note the preview URL, which follows this format:

https://{your-store}.myshopify.com/admin/scripts/preview?script_id={script_id}

When accessed, this preview link runs the temporary passthrough script instead of your published script, effectively disabling your current script's logic for that session.

Anchor to Step 2: Add testing logic to your FunctionStep 2: Add testing logic to your Function

In your Shopify Function, add logic to target specific test users. The most reliable method is using customer tags.

Anchor to Tag test customersTag test customers

In the Shopify admin, go to Customers and add a tag like TESTER to customers who should experience the new Function behavior.
In your Function's input query, include customer tag information:

src/run.graphql
query Input {
cart {
buyerIdentity {
customer {
hasAnyTag(tags: ["TESTER"])
}
}
# ... rest of your query
}
}

Anchor to Implement conditional logicImplement conditional logic

Add conditional logic in your Function to only apply new behavior to tagged customers:

File

// Check if the customer has the TESTER tag

let has_tester_tag = input

.cart()

.buyer_identity()

.and_then(|bi| bi.customer())

.map(|customer| customer.has_any_tag())

.unwrap_or(&false);

if *has_tester_tag {

// Apply new Function logic here

// ... your function implementation

} else {

// Return no changes (let existing script handle it)

return Ok(FunctionRunResult { operations: vec![] });

}

const customer = input.cart.buyerIdentity?.customer;

const hasTesterTag = customer?.hasAnyTag ?? false;

if (hasTesterTag) {

// Apply new Function logic here

// ... your function implementation

} else {

// Return no changes (let existing script handle it)

return { operations: [] };

}

// Check if the customer has the TESTER tag
let has_tester_tag = input
    .cart()
    .buyer_identity()
    .and_then(|bi| bi.customer())
    .map(|customer| customer.has_any_tag())
    .unwrap_or(&false);

if *has_tester_tag {
    // Apply new Function logic here
    // ... your function implementation
} else {
    // Return no changes (let existing script handle it)
    return Ok(FunctionRunResult { operations: vec![] });
}

const customer = input.cart.buyerIdentity?.customer;
const hasTesterTag = customer?.hasAnyTag ?? false;

if (hasTesterTag) {
    // Apply new Function logic here
    // ... your function implementation
} else {
    // Return no changes (let existing script handle it)
    return { operations: [] };
}

Anchor to Step 3: Deploy and test in productionStep 3: Deploy and test in production

You can test your Function in development and production.

Anchor to Development testingDevelopment testing

Test your Function thoroughly in a development store:

Terminal
shopify app dev
Verify that the Function behaves identically to your existing Shopify Script.

Anchor to Production deployment and testingProduction deployment and testing

Choose one of the following deployment methods:

Anchor to Option A: App with configuration UIOption A: App with configuration UI

If your Function is part of an app with a user interface, then use the app to enable and configure the Function in production.

Anchor to Option B: GraphiQL deploymentOption B: GraphiQL deployment

Note

This method works best for Functions that don't require ongoing merchant configuration.

If you have a custom Function without UI configuration, then complete the following steps:

Use the Shopify GraphiQL App to enable the Function directly.
Retrieve a list of available Functions using this query:

query.graphql
query getFunctions {
shopifyFunctions(first: 100) {
edges {
node {
id
title
apiType
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
Use the Function's id in the appropriate creation mutation for your Function type (for example, discountAutomaticAppCreate or deliveryCustomizationCreate).

Anchor to Testing processTesting process

Tag test users: Add the TESTER tag to select customers or your own test account.
Test with script preview: Have tagged users access your store using the preview link from Step 1 to disable the existing script.
Verify behavior: Ensure the Function produces the same results as the original Script for tagged users, while untagged users continue to experience the original Script behavior.

Anchor to Step 4: Complete the migrationStep 4: Complete the migration

After you've verified that the Function works correctly:

Remove testing code: Update your Function to remove the customer tag conditional logic.
Deploy the final version:

Terminal
shopify app deploy
Deactivate the Script: In your Shopify admin, go to Apps > Script Editor and unpublish your existing Script.

Anchor to Best practicesBest practices

Always test in a development store before deploying to production.
Keep the testing period short to minimize code complexity.
Monitor your store's performance and error logs after migration.
Have a rollback plan ready in case issues arise.
Document any differences in behavior between Scripts and Functions.
Test edge cases that might behave differently between Scripts and Functions.

Anchor to TroubleshootingTroubleshooting

You might encounter the following issue during migration:

Function not triggering: Verify the Function is properly enabled and configured.
Different behavior: Check for differences in input data structure between Scripts and Functions.

Anchor to Next stepsNext steps

Learn more about Shopify Functions.

Was this page helpful?