Task options

Every task script has access to an options object, which contains all of the merchant-configurable options for a task. (For more on where it can be used, see The options object.)

The simple act of referencing keys within this object – e.g. {{ options.foo }} – will cause Mechanic to make the referenced keys available to the merchant in an automatically-generated graphical form. In this way, we make it easy to generate merchant-friendly configuration, without having to do anything other than write the code you'd write anyway.


  • Option keys must only contain numbers, lowercase letters, and underscores.
  • Option keys must be used within standard Liquid tags (e.g. {% assign foo = options.bar %} or {{ options.baz }}) in order to be registered.


Mechanic supports several flags, which control what sort of data merchants may provide. Depending on the flags used for a specific options variable, Mechanic will enforce validations and/or construct the form element differently.

A option that uses a flag consists of the original option key, plus a double underscore, plus a set of underscore-delimited flags. This format looks like  options.foo__bar_baz , where foo  is the option name, and bar  and baz  are the flags.

Mechanic supports these flags:

  • required  – Guarantees that the merchant must fill in this option before the task can be saved
  • multiline  – Renders a textarea, into which multiple lines of text can be entered
  • email  – Renders an input element of type email
  • number  – Renders an input element of type number , with step="1"
  • code  – Renders a textarea that's formatted for code
  • keyval  – Allows the merchant to add labeled values, which are made available to the script as a key => value data structure, where each value is evaluated with the option's other flags
  • array  – allows the merchant to add a series of values, where each value is evaluated with the option's other flags; if the merchant adds a fifth element, a "Manage in bulk" option will appear, allowing for a larger set of elements to be pasted into a simple text box


This object is always a hash. Its keys exactly match the keys used in referencing this object – including any flags used for each key.

For example, consider this task script:

{% if options.send_email__boolean %}
  {% action "email" %}
      "subject": {{ options.email_subject | json }}
{% endaction %}
{% endif %}

If the merchant doesn't touch the resulting configuration form at all, the options object will contain this value when the task is run:

  "send_email__boolean": false,
  "email_subject": null

These defaults will be replaced by any merchant-configured values.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.