Configuration schema for payment methods scripts

To make your code reusable, you can replace hard-coded variables in your script with configurations. Configurations let merchants and staff customize your script by entering values and options in the Shopify admin. When your script runs, these values are passed to your script as input in key-value pairs.

Anatomy of script.json

You define properties for your script in the script settings file (script.json). The script.json file contains the script's settings, which include its title, description, and configuration schema. It's a required file that you need to edit even if your script doesn't use configuration values.

PropertiesRequired?Description
versionYesThe version of the schema. Don't edit this value.
titleYesThe title of the script.
descriptionYesA short description of the script.
configurationUiYesSpecifies whether Shopify admin renders a UI for the script. configurationUi is true, a UI is rendered. Valid values: true or false.
configurationYesDescribes the schema for the script's configurations. If your script doesn't use configurations, then set type to single and schema to [].

  • type (Required) - Specifies the type for the configurations. Valid values: single and list.
  • schema (Required) - An array that defines a configuration. When configurationUi is true, the properties in this array are rendered as input UI components in Shopify admin.
    • key (Required) - The key for the configuration. This value needs to match the configuration key that is used in the script. This property doesn't appear in the rendered UI.
    • name (Required) - The name of the configuration. Rendered as the label for the input component.
    • type (Required) - Th type of input component to render in the UI. Valid value: single_line_text_field.
    • helpText (Optional) - Hint text to help merchants know what to enter for the UI component. Displays as greyed text.
    • defaultValue (Optional) - Default value for the UI component. Displays as regular text.
  • Usage notes

    • For each configuration that you use in your script, define a schema array in script.json. Make sure that the key in your configuration.get call in your script matches a value for the key entry in the schema array.

    • Only text (string) fields are supported as input. Empty fields are saved as "".

    • Text markup isn't supported. Font formatting, such as italics, strong, and underlining, isn't supported. Working links also aren't supported.

    • The Shopify admin UI doesn't validate any of the values entered. You need to add validations 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.

    Examples

    The following section shows examples of scripts that use and don't use configurations. Configurations can accept single values or a list of values.

    Single value configurations

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

    The corresponding script.json file 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 file for the above script looks like the following:

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

    No configurations

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

    Next steps

    • Create a payment methods script that lets merchants customize the payment method names offered to their customers at checkout.
    • Create a shipping methods script that allows merchants to hide a shipping method offered to their customers at checkout based on a customer tag.