Add configurations to scripts

Replace hard-coded variables in your script with configurations. You can set their values when you turn on and configure your script by using the shopify script enable command. When your script runs, these values are passed to your script as input in key-value pairs.

Define the schema for your configurations in script.json and use them in your code. Configurations can accept single values or a list (an array).

Steps

  1. In script.json, define the configuration schema for each configuration that you want to use in your script. For example:

  2. In your script, use configuration.get to retrieve the configuration values.

    Make sure that your key in the configuration.get method in your script matches a value for key in the configuration schema. When your configuration is a list, you can also use the ConfigurationList class to work with the configuration.

  3. Validate and type cast the configuration values in your script. Currently, the only way to validate configuration values is within your script. Consider adding checks, such as the following to your script:

    • Type cast data types and check the format of values. All configuration values are saved as strings. If your script expects the configuration value to be numerical type, then your code needs convert it. Use the safeParseInt function to type cast strings to integers. If your script expects the value to be in a specific format, then check for this format in your script.
    • Check for empty strings and missing configuration values. Use configuration.exists to check for missing values.
  4. Test the configurations in the unit tests.

Examples

Single configurations

In the following example, the script expects that each configuration is a single value.

The corresponding script.json for the above script looks like the following:

For the above example, the configuration values are saved as the following key-value pairs:

List configurations

Use the ConfigurationList object to handle list configurations.

In the following example, the script expects that the configuration is a list:

The corresponding script.json for the above script looks like the following:

For the above example, the configuration values are saved as the following key-value pairs:

Script settings when there are configurations

The following example is a configuration schema for a script that doesn't use configurations

Learn more

On this page