---
title: Migrating from Shopify Scripts to Shopify Functions
description: >-
  Learn how to safely migrate your existing Shopify Scripts to Shopify
  Functions.
source_url:
  html: 'https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts'
  md: >-
    https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md
---

ExpandOn this page

* [What you'll learn](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#what-youll-learn)
* [Requirements](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#requirements)
* [Function APIs mapping](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#function-apis-mapping)
* [Step 1: Create a preview link for your existing script](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#step-1-create-a-preview-link-for-your-existing-script)
* [Step 2: Add testing logic to your Function](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#step-2-add-testing-logic-to-your-function)
* [Step 3: Deploy and test in production](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#step-3-deploy-and-test-in-production)
* [Step 4: Complete the migration](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#step-4-complete-the-migration)
* [Best practices](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#best-practices)
* [Troubleshooting](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#troubleshooting)
* [Next steps](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#next-steps)

# Migrating from Shopify Scripts to Shopify Functions

Functions availability

* 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](https://help.shopify.com/manual/intro-to-shopify/pricing-plans/plans-features/shopify-plus-plan) can use [custom apps](https://help.shopify.com/manual/apps/app-types/custom-apps) that contain [Shopify Function APIs](https://shopify.dev/docs/api/functions).
* Some Shopify Functions capabilities are available only to stores on a [Shopify Plus plan](https://help.shopify.com/manual/intro-to-shopify/pricing-plans/plans-features/shopify-plus-plan). See [Shopify Function APIs](https://shopify.dev/docs/api/functions#availability-of-shopify-functions) 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.

***

## What 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.

***

## Requirements

* You have an existing Shopify Script that you want to migrate.
* You have access to a [development store](https://shopify.dev/docs/api/development-stores#create-a-development-store-to-test-your-app) for initial testing.
* You're familiar with [creating Shopify Functions using Shopify CLI](https://shopify.dev/docs/api/functions/latest#shopify-cli-scaffold).
* You have the necessary permissions to use the Script Editor app in the target store.

***

## Function 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](https://shopify.dev/docs/api/functions/latest/discount) | Apply discounts to products, or the entire cart. |
| Line item scripts | [Cart Transform API](https://shopify.dev/docs/api/functions/latest/cart-transform) | Modify cart line items (bundle, merge, or add items). |
| Line item scripts | [Cart and Checkout Validation API](https://shopify.dev/docs/api/functions/latest/cart-and-checkout-validation) | Validate cart contents and block checkout under certain conditions. |
| Shipping scripts | [Delivery Customization API](https://shopify.dev/docs/api/functions/latest/delivery-customization) and [Discounts API](https://shopify.dev/docs/api/functions/latest/discount) | Hide, rename, or reorder delivery methods, and apply discounts to delivery methods. |
| Payment scripts | [Payment Customization API](https://shopify.dev/docs/api/functions/latest/payment-customization) | Hide, rename, or reorder payment methods. |

***

## Step 1: Create a preview link for your existing script

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

1. In the Shopify admin, go to **Apps** > **Script Editor**.

2. Create a temporary script with the following code but don't publish it:

   Output.cart = Input.cart

3. 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.

***

## Step 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.

### Tag test customers

1. In the Shopify admin, go to **Customers** and add a tag like `TESTER` to customers who should experience the new Function behavior.

2. In your Function's input query, include customer tag information:

   ## src/run.graphql

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

### Implement conditional logic

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

## File

```rust
// 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![] });
}
```

```javascript
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: [] };
}
```

##### Rust

```
// 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![] });
}
```

##### JavaScript

```
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: [] };
}
```

***

## Step 3: Deploy and test in production

You can test your Function in development and production.

### Development testing

1. Test your Function thoroughly in a development store:

   ## Terminal

   ```shell
   shopify app dev
   ```

2. Verify that the Function behaves identically to your existing Shopify Script.

### Production deployment and testing

Choose one of the following deployment methods:

#### Option 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.

#### Option B: Graphi​QL 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:

1. Use the [Shopify GraphiQL App](https://shopify-graphiql-app.shopifycloud.com/) to enable the Function directly.

2. Retrieve a list of available Functions using this query:

   ## query.graphql

   ```graphql
   query getFunctions {
     shopifyFunctions(first: 100) {
       edges {
         node {
           id
           title
           apiType
         }
       }
       pageInfo {
         hasNextPage
         endCursor
       }
     }
   }
   ```

3. Use the Function's `id` in the appropriate creation mutation for your Function type (for example, [`discountAutomaticAppCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/discountAutomaticAppCreate) or [`deliveryCustomizationCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryCustomizationCreate)).

### Testing process

1. **Tag test users**: Add the `TESTER` tag to select customers or your own test account.
2. **Test with script preview**: Have tagged users access your store using the preview link from Step 1 to disable the existing script.
3. **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.

***

## Step 4: Complete the migration

After you've verified that the Function works correctly:

1. **Remove testing code**: Update your Function to remove the customer tag conditional logic.

2. **Deploy the final version**:

   ## Terminal

   ```shell
   shopify app deploy
   ```

3. **Deactivate the Script**: In your Shopify admin, go to **Apps** > **Script Editor** and unpublish your existing Script.

***

## Best 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.

***

## Troubleshooting

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.

***

## Next steps

* [Learn more about Shopify Functions](https://shopify.dev/docs/api/functions).

***

* [What you'll learn](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#what-youll-learn)
* [Requirements](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#requirements)
* [Function APIs mapping](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#function-apis-mapping)
* [Step 1: Create a preview link for your existing script](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#step-1-create-a-preview-link-for-your-existing-script)
* [Step 2: Add testing logic to your Function](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#step-2-add-testing-logic-to-your-function)
* [Step 3: Deploy and test in production](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#step-3-deploy-and-test-in-production)
* [Step 4: Complete the migration](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#step-4-complete-the-migration)
* [Best practices](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#best-practices)
* [Troubleshooting](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#troubleshooting)
* [Next steps](https://shopify.dev/docs/apps/build/functions/migrating-from-shopify-scripts.md#next-steps)