Options

Tasks can accept user configuration via options. Options are created automatically: when you reference options.something in your task's code, Mechanic adds an input field for it in the task configuration UI.

You can add flags to an option key (like __required or __select_...) to control what kind of input is shown and how it's validated.

Mechanic flags provide only limited option validation. For anything more advanced, a task can define custom validation.

Quick start

Paste any of these into your task code (even inside a {% comment %} block) to create an option:

Options flagged with __userform will also appear on the Run task form for tasks that subscribe to mechanic/user/form.

{{ options.note }}
{{ options.subject__required }}
{{ options.body__multiline }}
{{ options.reply_to__email_required }}
{{ options.channels__multiselect_o1_email_o2_sms }}
{{ options.enabled__boolean }}
{{ options.count__number }}
{{ options.tags__array }}
{{ options.mode__select_o1_test_o2_live }}
{{ options.run_mode__select_o1_test_o2_live__userform__required }}

1. Keys

Options are available in the options Liquid variable. Each option key becomes one field in the UI, and one value at runtime.

Option keys must contain only lowercase letters, numbers, and underscores. Mechanic uses the key to generate a label (underscores become spaces).

<name>[__<flag>[ _<flag> ... ]][__<flag>[ _<flag> ... ] ...]

Part	Rules	Example
name	Lowercase letters, numbers, and underscores only.	send_after
flag	One or more tokens that customise the field (see below).	required, date, picker_product

Flags are usually specified after the first __, separated with underscores (_). For complex option types (notably select / choice / multiselect), you may also append additional flag segments using __ (e.g. __userform__required) to avoid accidentally changing the last choice value.

Mechanic finds options by scanning your task code, so each option must be referenced at least once using a normal lookup like options.foobar.

---

2. Display Order

Options are displayed to the user in the order in which they are first referenced in the task code.

Because this may not result in a natural sequence, it can be useful to prefix task code with a comment block, explicitly referencing each option so as to force the overall order.

{% comment %}
  Option order:

  {{ options.api_key__required }}
  {{ options.mode__select_o1_test_o2_live }}
  {{ options.webhooks__array }}
{% endcomment %}

---

3. Flags

Option flags control how an option appears and behaves in a task's configuration form, and also control the type and format of the option value.

Many flags may be combined with other flags, for more nuanced control.

If no flags are used for an option, an option will be made available as a plain text field, and the option value will be a string.

The special userform flag does not change the input type or validation; it simply marks an option as one that should appear on the Run task form (topic mechanic/user/form) in addition to the general task options screen.

Flags fall into three categories:

Category	Purpose
Input types	Choose what kind of input you want (date picker, slider, select list, …). Pick exactly one input-type.
Form modifiers	Fine‑tune how the control validates or behaves (required, email, etc.).
Auxiliary flags	Extra behaviour for certain input types (future‑only dates, multi‑select choices, etc.).

3.1 Input‑type flags

Flag	UI control	Value returned	Key examples
(none - default)	Single‑line text	string	options.subject
multiline	Multiline text box	string	options.body__multiline
boolean	Checkbox	true/false	options.enabled__boolean
number	Numeric input (step=1)	number	options.count__number
code	Code‑formatted text area	string	options.script_snippet__code_multiline
keyval	Key → value repeater	hash	options.headers__keyval
array	Value repeater	array	options.tags__array
date	Calendar picker	"YYYY‑MM‑DD"	options.launch_date__date
datetime	Date+time picker	"YYYY‑MM‑DDTHH:MM"	options.send_at__datetime
time	Time‑only picker	"HH:MM"	options.quiet_time__time
color	Hex colour picker	"#RRGGBB"	options.theme_color__color
range_minX_maxY_stepZ	Slider + number box	number	options.qty__range_min0_max100_step5
select	Single‑choice dropdown	string	options.plan__select_o1_basic_o2_pro
choice	Radio buttons	string	options.tier__choice_o1_gold_o2_silver
multiselect	Checkbox list	array[string]	options.channels__multiselect_o1_email_o2_sms
picker_<resource>	Shopify resource picker	gid string	options.product__picker_product
picker_<resource>_array	Multi‑select resource picker	array[gid]	options.products__picker_product_array

Array options have a hidden feature: once the user-configured array reaches 5 elements in size, a new "Manage in bulk" button will appear for that option. Clicking it will open a modal which allows the user to manage the array's input using a single multiline text field, in which each line represents an array element. This is a convenient way to configure larger arrays.

Choice/Select grammar

Use ordinal tokens to define values:

<name>__select_o1_basic_o2_pro_o3_enterprise
               │  │     │  │
               │  │     │  └───── value #2
               │  │     └──────── ordinal marker
               │  └──────────── value #1
               └─────────────── ordinal marker

Ordinals (o1, o2, …) determine display order. Underscores inside values are preserved.

Because flags are parsed from underscore-separated tokens, avoid using flag words like required and userform as literal choice values.

Combining choice/select with userform / required

For select, choice, and multiselect, prefer appending modifier flags as additional __ segments:

• options.aggregate__select_o1_first_o2_last_o3_sum__userform__required

Appending modifiers at the end of the same underscore-delimited segment also works:

• options.aggregate__select_o1_first_o2_last_o3_sum_userform_required

Do not put modifiers before the input-type flag (e.g. options.aggregate__userform_select_... or options.aggregate__required_select_...).

Range grammar

• min<number> – required

• max<number> – required

• step<number> – optional (defaults to 1).

Picker grammar

<name>__picker_<product|variant|collection>[_array]

• Append _array for multi‑select.

• Unsupported resources are rejected during validation.

3.2 Form‑modifier flags

Flag	Applies to	Effect
required	Any	Field must be filled before Save.
email	text	Adds email placeholder and basic email format check.
userform	Any	Shows this option on Run task form (mechanic/user/form).

3.3 Auxiliary flags

Flag	Works with	Effect
futureonly	date, datetime	Picker disallows past dates.

---

4. Built‑in validation

1. Required fields must not be empty.

2. Range sliders need both min and max.

3. Pickers only allow product, variant, or collection.

4. Email inputs are matched against a basic regex.

Custom rules? Learn more about custom validation.

---

5. Liquid

Options that allow text input are evaluated for Liquid when a task processes an event. Liquid evaluation for options occurs before it occurs for task code, which means that any Liquid variables created by task code are not available to task options.

Liquid code in task options have access to the same set of environment variables that are made available to the task code, including event, shop, cache, and any event subject variables.

---

6. Quick reference

Goal	Key snippet	Value example
Text input	options.subject	"Welcome!"
Text input (required)	options.subject__required	"Welcome!"
Email input	options.reply_to__email_required	"[email protected]"
Checkbox	options.newsletter__boolean	false
Key–value map	options.headers__keyval	{ "X-Env": "staging" }
String list	options.tags__array	["vip","wholesale"]
0–100 slider	options.score__range_min0_max100	42
Colour picker	options.bg__color	"#336699"
Dropdown	options.plan__select_o1_basic_o2_pro	"basic"
Run task dropdown	options.plan__select_o1_basic_o2_pro__userform__required	"basic"
Multi‑select	options.channels__multiselect_o1_email_o2_sms	["email","sms"]
Product picker	options.promo__picker_product	"gid://shopify/Product/123"
Product list	options.products__picker_product_array	[ "gid://…/1", "gid://…/2" ]
Date	options.go_live__date_required	"2025-05-06"
Time	options.quiet_at__time	"00:25"
Datetime	options.party__datetime	"2031-04-22T15:13:00"

Working with date options

Formatting date/time option values

{{ options.launch_date__date | date: "%Y-%m-%d" }}
   ⇒ 2025-05-06

{{ options.quiet_at__time  | date: "%H:%M" }}
   ⇒ 00:25

{{ options.party__datetime     | date: "%Y-%m-%d %H:%M" }}
   ⇒ 2031-04-22 15:13

Converting to another timezone

{{ options.party__datetime | date: tz: "UTC" }}
   ⇒ 2031-04-22T19:13:00Z       {offset shifted +4 h}

{{ options.quiet_at__time | date: "%H:%M %Z", tz: "America/Vancouver" }}
   ⇒ 21:25 PDT