Creating and using scripts in Script Editor

You can create and run scripts on your online store's cart by using the Script Editor.

Shopify Plus

Scripts and the Script Editor app are available to Shopify Plus merchants only.

Creating new scripts

When the Script Editor is installed in your store, you can use it to create scripts. Visit the Shopify scripts API documentation for a reference on writing code for scripts.

  1. From your Shopify admin, click Apps (or press G A):

    Click Apps in the admin navigation
  2. Click Script Editor. The Scripts overview page shows a list of scripts for your store.

    Creating new script img2
  3. Click Create script to begin creating a new script.

    Click Create script
  4. In the Select script template dialog:

    1. Choose the type of script that you want to create.
    2. Choose an example template as a starting point, or choose Blank template to start writing a script from scratch.
    3. Click Create script to create a script with the type that you have chosen.

      Tip

      The type of script you choose here (Line items or Shipping rates) determines the script's type, and the methods that the script will be able to use. The script type that you choose in this step cannot be changed later.

  5. In the Title box, enter a name for the script. Use a descriptive name so you can tell what the script does at a glance.

  6. Click Code to open the Ruby source code console.

  7. Enter the code for your script. Use the Shopify scripts API documentation as a reference. Remember that your script can only access the methods available to its type. For example, a line item script cannot use shipping methods.

  8. Click Run script to run the script.

  9. When you are finished:

    • click Save draft to save an unpublished draft of the script
    • click Save and publish to create and publish the script.

    Tip

    You can publish one script per script type. For example, you can publish a line items script and a shipping rates script, but you can't publish two line items scripts at the same time.

Script templates

When you choose to create a new script, you can choose from a few templates that will let you start writing code for specific scripts faster. The following templates are available:

  • Percentage (%) off a product
  • Amount ($) off a product
  • Percentage (%) and amount ($) off a product
  • Tiered discounts
  • Buy one get one free (BOGO)
  • Blank template (that is, no template code)

When you create the script, the Ruby source code box contains the default code for the template that you chose. You can use the template code to start writing your script.

The Script Editor documentation also has more script examples.

Testing scripts

While you are working on a script, you can test it from within the Script Editor to make sure it works.

To test a script:

  1. From your Shopify admin, click Apps (or press G A):

    Click Apps in the admin navigation
  2. Click Script Editor.

  3. Click the name of the script that you want to test.

  4. To edit a test cart, click Input. You can also click Both to see the script code and the test cart at the same time:

    Click 'Input' in the Script Editor

    The input view shows options for editing a cart to test your script. You can add products, customers, discount codes, customer information, and shipping information based on what you want to test your script against.

    • Type in the Products section to search for and add products to the test order.
    • Type in the Discount code section to search for and add discount codes to the test order.
    • Type in the Customer information section to search for and add customers to the test order.
    • Click Add or Edit in the Shipping address section to change the shipping address for the test order.
  5. Click Run script to see the changes that the script makes to your test cart.

    Click Run script

    If your script runs successfully, then the Output section will update to show the changes applied by the script. If the Output section doesn't change, or there are unexpected changes, there might be errors in your script. Check the Console box in the Ruby source code section to resolve any script errors:

    View test cart output

    The Console box will report the script's resource usage. More complex scripts will use more resources. Scripts have a limited amount of CPU and memory available to them.

  6. When you are finished, click Save draft to save the script or click Publish to save publish the script.

Error checking and debugging

The Script Editor will check your code for basic errors while you're writing a script.

It's a good idea to correct errors in your script before testing or publishing it. If your script has syntax errors, then testing your script won't work.

If you need more information on a script error, hover over the red x icon in the Script Editor's margin:

Hovering over the X in the Script Editor margin reveals details about syntax errors

The Script Editor will also report errors that occur in your published scripts:

Screenshot of errors published scripts in the Script Editor

Production errors

Production errors are errors that occur in published scripts when they are run in your online store. Often production errors occur because a customer's checkout contains items that were not originally accounted for when the script was written and tested. From the Scripts page, you can see the scripts that have had production errors:
Screenshot of the Scripts page that highlights the production error counts for a script.

Details about the error, including a snapshot of the checkout cart contents and error messages, are captured and are connected to the script. You can use this information to replicate the cart inputs when you debug and test the script.

Before you can debug a script that is published, you need to unpublish the script. If you need a copy of the script to continue running in your online store, then duplicate the script and publish the duplicate copy. You want to debug the script that actually produced the error, because this version of the script has the error details connected to it.

Debugging production errors

To debug production errors:

  1. In the Script Editor app, duplicate the published script that contains the errors.

    1. Open the Script Editor app. The Scripts overview page shows a list of scripts for your store, as well as their error counts:
      Screenshot of the Scripts page.
    2. Click the name of the published script that you want to debug.
    3. Click Duplicate to create a copy of that script.
  2. Publish the duplicate script, so that you do not disrupt your online store while you debug the original script.

    1. Click Save and Publish.
    The status of the original script is now set to draft:
    Screenshot showing a original script and it's published duplicate.
  3. Debug the script. Use the error details that are connected to the script to replicate the errors, make changes to the code, and test your results.

    1. From the Scripts page, click the name of the script that you want to debug.
    2. Click the notification that lists the number of production errors that have occurred in the script:
      Screenshot that highlights the number of production errors.
    3. Click the name of the production error that you want to investigate:
      Screenshot of the list of production errors for the script.
      Details about the error appears:
      Screenshot that shows the details of an error including the checkout snapshot.
      The Input panel contains the contents of the checkout at the time of an error. You can click the left and right arrows to view what was in checkout each time the error occured. Stop clicking when you find a checkout that you'd like to use as the cart input when you debug and test your script.
    4. Click Debug to open the page where you can test and debug the script:
      Screenshot that highlights the Debug button.
      The Cart input panel contains the contents of the checkout that you chose in the previous step:
      Screenshot that shows the Cart input panel.
  4. Debug the script. Use the same investigation and testing techniques that you used to test it originally. See Testing scripts.

  5. When you are satisfied with your changes, click Save and Publish to publish the updated version of the script. When the script is published, information about its production errors disappear.

  6. Delete the duplicate copy of the script.

Publishing and unpublishing scripts

You can publish or unpublish existing scripts from within the Script Editor app. Only one script per script type can be published at the same time. For example, you can publish a line items script and a shipping rates script, but you can't publish two line items scripts at the same time.

The current published script cannot be changed. To edit a published script, you must unpublish it, edit the draft, and then publish it again.

You can also duplicate a script and use it as a starting point to create a new script or to test existing scripts. See Debugging production errors.

Publishing a script does not apply its discounts to existing carts. Similarly, unpublishing a script does not remove discounts that the script has applied to existing carts.

When you publish a script, error counts for the script are reset to zero and any error information that was connected to the script disappears.

When you publish a script, your email address is automatically subscribed to receive notifications if the script causes any production errors. Notifications are sent in regular intervals after the first error occurs. For example, you will receive an error when the first error occurs. If you do not fix this error, then you will receive another notification when the tenth error occurs, when the 100th error occurs, and so on. You can unsubscribe from these notifications from the Production errors page:

Screenshot of the Production errors page showing the Unsubscribe button.

Publishing a script

  1. From your Shopify admin, click Apps (or press G A):

    Click Apps in the admin navigation
  2. Click Script Editor.

  3. Click the name of the draft script that you want to publish.

  4. Click Publish or Save and publish to save changes to the script and publish it:

    Click save and publish

Unpublishing a script

  1. From your Shopify admin, click Apps (or press G A):

    Click Apps in the admin navigation
  2. Click Script Editor.

  3. Click the name of the published script that you want to unpublish.

  4. Click Unpublish to make the script an unpublished draft.

Duplicating a script

To duplicate a script:

  1. From your Shopify admin, click Apps (or press G A):

    Click Apps in the admin navigation
  2. Click Script Editor.

  3. Click the name of the script that you want to duplicate.

  4. Click Duplicate to make a copy of the script.

Want to discuss this page?

Visit the Shopify Community

Ready to start selling online with Shopify?

Try it free