Mechanic's automation tasks are written in Liquid, which is a template language used heavily in and around Shopify. This means that developers of all levels, with even a little Shopify development experience, can get started with Mechanic.

To find a developer for hire, you can contact Mechanic Partners directly at partners.mechanic.dev. This is a growing list of established developers, both independent and agency, who can help you with your implementation.

This is a super common path, and the Mechanic community is here to help. :)

If you already have a developer on your team, or have an existing connection to a developer, send them this article and see if they can help you!

Mechanic is a development platform – in the hands of a developer, it can be used to accomplish almost anything in Shopify. While our covers many use cases, Mechanic's true strength is in letting developers solve merchant problems quickly, giving merchants easy configuration forms for managing the resulting tasks.

If you're using AI...

Tread lightly! We've got notes on this here: .

If you need a developer…

Mechanic's automation tasks are written in Liquid, which is a template language used heavily in and around Shopify. This means that developers of all levels, with even a little Shopify development experience, can get started with Mechanic.

To find a developer for hire, you can contact Mechanic Partners directly at . This is a growing list of established developers, both independent and agency, who can help you with your implementation.

Lastly: if you already have a developer on your team, or have an existing connection to a developer, send them this article and see if they can help you!

If you are a developer…

If you're familiar with Liquid, and Shopify's Admin APIs, start by picking something from our that's close to what you're looking for, then modify it as needed.

Make sure to take advantage of the documentation found here, beginning with the section. Mechanic is a powerful system, and grounding yourself in the fundamentals is a good way to begin.

Finally, join Mechanic's Slack workspace at to exchange support with the community. The #general channel is a great place to start, and it's filled with people who are using Mechanic to solve problems every day. :)

Shopify is evolving its platform to enhance performance and provide more powerful features. As part of this evolution, Shopify has announced the deprecation of the Shopify Admin REST API. In response, we are updating our services to align with this change, transitioning fully to the GraphQL Admin API.

What Is Changing?

• Deprecation of REST Admin API: Starting October 1, 2024, the REST Admin API is considered a legacy API. Shopify will begin phasing it out, with critical endpoints like product and variant endpoints ceasing to function on February 1, 2025. While product and variant endpoints are the first to be deprecated, Shopify plans to deprecate all REST endpoints in the future.

• GraphQL Admin API: All new developments and updates will utilize the GraphQL Admin API exclusively. This shift is aimed at leveraging the enhanced capabilities and efficiencies that GraphQL offers.

Why is Shopify Making this Change?

Shopify wants to maintain one API and have decided to discontinue the REST Admin API in favor of the GraphQL Admin API. GraphQL addresses several limitations of REST, offering significant benefits such as:

• Efficient Data Retrieval: Fetch precisely the data you need in a single request.

• Enhanced Flexibility: Customize queries to suit your specific needs.

How Does This Affect You?

• Library Tasks Update: All our library tasks will be updated to use GraphQL only. You will get a notification via email and in app if there is an update available for a task you have installed. Tasks that can be auto-updated will be updated for you. These updated tasks will serve as examples to help you migrate your custom tasks.

• Custom Tasks Migration: If you have custom tasks relying on the REST API, they will need to be migrated to use the GraphQL API before the deprecation deadlines. See our guide .

• Action Required: To ensure uninterrupted service, please begin updating your custom tasks to GraphQL as soon as possible.

Specific Impacts

After February 1, 2025:

• Product and Variant REST liquid objects will cease functioning

• for Product and Variants will now pass resource IDs instead of full REST objects - tasks will need to look up objects using these IDs

• REST lookups in email task options will no longer work

• Any tasks using REST API for product/variant operations will stop working

We recommend migrating all tasks to GraphQL now, not just those affected by the February deadline, as all REST endpoints will eventually be deprecated.

Next Steps

1. Review Our Migration Guides: We have prepared comprehensive guides to assist you in migrating your custom tasks to GraphQL. Access them .

2. Update Tasks from the Library: You will get a notification via email and in app if there is an update available for a task you have installed. Tasks that can be auto-updated will be updated for you.

3. Learn More About GraphQL: Familiarize yourself with GraphQL by visiting Shopify's official .

Getting Help

• Hire a Partner: Browse our for expert help

• Community Support: Join our to ask questions about migrating your tasks

Mechanic's task library is a compendium of e-commerce automation tasks and documentation, written by the Mechanic community and the Mechanic core team. , everything is open-sourced under the highly permissive , making all library tasks appropriate for re-use and modification.

When building a new task, it's often easier to modify an existing task than to create a task from scratch. Searching GitHub is a good place to start, when looking for inspiration.

To browse the task library, visit .

The Mechanic community can request new tasks – see .

The task library is open for contributions, by way of pull requests – see .

Mechanic is a Shopify development and automation platform.

• Search the task library for an off-the-shelf solution

• Learn about "going custom" for a task that fits you perfectly

• Ask in our community Slack workspace if you need something else

Can Mechanic help me?

Mechanic is a Shopify development and automation platform, which comes with a rich library of pre-written automation tasks – and our users write their own custom tasks every day. Let's find out if Mechanic might work for you.

1. Are you working on something Shopify-related?

   • Mechanic is only available for Shopify.

2. Is what you're looking for already available from Mechanic's task library?

   • We have hundreds of common scenarios already handled with pre-written, open-source, modifiable, off-the-shelf tasks.

3. As far as your problem concerns Shopify data, is what you want to do supported by the Shopify Admin API?

   • Mechanic's toolkit goes beyond Shopify's APIs, but a Mechanic task can only interact with Shopify data in ways that Shopify supports.

4. Are you open to going custom?

   • Whether you need a developer or already have that covered, the path to creating a custom Mechanic task is well-established.

That list wasn't exactly a formal flowchart, but we hope it's helpful as you're evaluating Mechanic for your purposes. At its best, Mechanic is a platform and toolkit that you go to, and return to, when you hit the limits of the Shopify admin. And it's a community that collectively has learned how to solve many, many kinds of problems. (Join our community Slack workspace!)

How does Mechanic work?

Tasks, events, and actions

A developer writes tasks – Mechanic's term for a piece of automation. These tasks can respond to many different events, like a Shopify webhook, a manual trigger, a regular interval (e.g. hourly, daily), or an incoming email. Tasks use subscriptions to signal their interest in specific event types.

When a task receives an incoming event, it can choose to generate an action – an operation that has an effect.

• The Shopify action makes changes to a Shopify store, like tagging, publishing, creating or deleting resources. It provides direct and complete access to Shopify's admin API, with support for both REST and GraphQL.

• The Email action is for sending email. It supports custom templates, and attachments.

• The FTP action is for uploading files to an FTP or SFTP server. These files may be generated by the task, or can be fetched from external locations.

• The HTTP action performs any request, to any HTTP endpoint. This facilitates integration with third-party APIs.

• The Files action generates a variety of file formats, including PDF, CSV, ZIP, and anything retrieved from a public URL. Files generated this way receive a temporary URL of their own, and can be fed into other tasks for further processing.

For a complete list of supported actions, see Actions.

Liquid

Mechanic makes heavy use of Liquid – a template language created by Shopify. Its primary use is in task code. In the same way that a Liquid theme receives browser requests and renders HTML, a Mechanic task receives events, and renders actions (by defining them with JSON).

In Mechanic, our Liquid implementation includes additional support for constructing arrays and hashes, and includes many useful filters, making data processing more efficient.

Run queues

Mechanic performs work using queues of runs, with no limit on how large each queue can become. If there is a sudden surge of incoming events for a Shopify store, the store's dedicated Mechanic queue could become delayed. This is an important difference between Mechanic and many other systems: in a high-traffic period, Mechanic will never refuse incoming events for a store; instead, it will process each one as soon as possible, by putting them into a run queue. The rate at which Mechanic processes work varies, depending on concurrency and the Shopify API rate limit.

Mechanic was made for working together. Our Slack workspace is where hundreds of folx compare implementation notes, collaborate on projects, and talk about the evolution of Mechanic itself – and it's the best place to ask your questions. You are always invited. :)

Join the Mechanic Slack workspace

In Mechanic, an event represents anything that happens. This could be an order being paid, or a customer record being created, or a fulfillment being delivered.

An event always has a topic, and data (even if the data is null/nil). Event attributes may be referenced in Liquid using the Event object.

Events may trigger any number of tasks, resulting in any number of actions.

Events are fed into Mechanic by the responsible party – for events that are about things in Shopify, for example, the events come to Mechanic from Shopify itself.

Getting help with custom tasks

Slack Community

• Community Support: We encourage you to join our Slack community, where you can seek advice and share experiences with other Mechanic developers. Often, community members can offer insights or solutions based on their experiences.

• Joining the Community: You can join our Slack community through the following link: .

Hiring a Developer

• Partner Directory: We recommend hiring a developer if the issue requires more in-depth technical expertise. Our partner directory lists qualified developers familiar with Mechanic task development.

• Finding a Developer: Visit our partner directory at to find a developer who can customize or optimize your task. If you want to be matched with a suitable developer, use our .

AI thrives on good examples. Our task library — — is full of good examples.

And if you get too stuck, hire a human. :) We've got those at .

Hey there! :) I'm Isaac, the creator of Mechanic. Those two lines above are the most important things to know. Keep reading if you're curious.

AI makes it super easy to create code. This is awesome. I'm so, so excited about this. The more the merrier.

This means Mechanic needs to learn something too: how to work with AI coders that can easily produce well-formed code but might not understand the patterns that Mechanic itself strictly abides by.

An AI can rapidly produce code, and it'll be good-looking code, but if the AI doesn't understand Mechanic the code might not work at all. In a very real way, it becomes a case of Mechanic not understanding the AI.

This is an interesting bind: because AI changes faster than Mechanic, it becomes a question of how best to guide the AI. For folks who understand code less than the AI, this puts everyone in a rough position: the AI is doing its best but can't tell when it doesn't understand, and the human is doing their best but can't tell when the AI doesn't understand, and all Mechanic knows is that it's being given something it doesn't understand.

As of this writing (currently June 12, 2025), AI is getting better at Mechanic. It's definitely getting better. But, still:

• AI code often "invents" Mechanic features that do not exist (like writing task code in YAML, or compiling action objects into a JSON array)

• AI code often fails to invoke necessary Mechanic features (like !).

• Intelligence is a game of guessing intelligently: AI often sort of just guesses at what task code is supposed to generate.

Mechanic, as a platform, is a place for solving things together. "Together" works best when everyone's honest about where they're at. Mechanic's a good place for that. :)

The AI path with Mechanic is getting better, but it's not smooth yet. If you're having trouble with this, head to — that page has an overview of the smooth paths that do exist.

To learn about how we at Lightward Inc roll with AI, please visit , and say hello. :)

No matter what: thank you for being here. ❤️

=Isaac

When a task subscribes to the mechanic/user/form event topic a "Run task" button is added to the task.

When the Run Task button is clicked the user is presented with a form that contains any that have the _userform flag.

When submitted, an event is generated, to which only this task will respond. The event contains the user's input in its data, making user's input available in event.data.

Getting the user’s input in code

During a mechanic/user/form event, the ad-hoc values arrive under event.data.

Mechanic tasks may be imported and exported as JSON, using the "Import" or "Export" button below the task editor. The JSON schema used for representing tasks is identical to that used by the task library, making it suitable for .

Importing

Mechanic has the ability to import tasks from JSON individually and in bulk, from the "Import tasks" screen.

Each task loaded via this route may be saved as a new task, or – if the task name exactly matches the name of a task already in the Mechanic account – it may be saved over the existing task. This latter path provides a way for batches of updated tasks to be loaded into a Mechanic account all together, preserving the version history for each task.

To import one or more tasks from a JSON export, use the "Import tasks" button on the Mechanic home screen.

On the next screen, follow the prompts to load your JSON task exports into Mechanic.

Importing in the task editor

When working in the task editor for a specific task, use the "Import" button to load in task JSON and have it applied to the current task.

Exporting

When viewing the task list on the Mechanic home screen, use the "Export" button after selecting one or more tasks to copy a JSON export of all tasks to the clipboard. This export can be used with Mechanic's task import area, described above.

Exporting from the task editor

When working in the task editor for a specific task, use the "Export" button to copy a JSON representation of the current task to the clipboard.

A task may enforce custom validation for options by including validation logic in its code, inspecting the current value of an option and rendering an if the option does not meet its criteria.

A modification to a task option will always result in a new being rendered. In this way, a task developer may provide the user with immediate feedback on their task configuration.

Example

In this example, a task begins by validating an option called "A positive number". The only flags on this option are "required" and "number", meaning that Mechanic's involvement is limited to making sure the user fills in this task option with a number.

Once the option is filled in, the task preview will be rendered. If the user has entered a zero, or a negative number, the is used to generate an . The error message will then be shown to the user, and they will be prevented from saving the task until they provide valid input.

Shopify does not offer a strict guarantee on webhook delivery. In rare cases (and usually in high-volume situations), we've observed Shopify fail to send a webhook.

Quoting from for this scenario:

Your app shouldn't rely solely on receiving data from Shopify webhooks. Because webhook delivery isn't always guaranteed, you should implement reconciliation jobs to periodically fetch data from Shopify.

This applies to Mechanic tasks as well (which are, essentially, tiny apps).

For tasks that respond to events on Shopify resources, we recommend the following, using shopify/orders/create as an example:

1. Update the task code to mark orders as having been processed. This could take the form of an order tag (e.g. "processed-by-task-xyz"), or a metafield. Additionally, ensure that this code skips orders that are already marked as processed.

2. Add a , like mechanic/scheduler/15min. Then, update the task code so that these scheduled runs are used to scan for and process new orders in the last 15 minutes that have not yet been processed. This is the reconciliation step, ensuring that all new orders are ultimately processed, one way or another.

Example

A task's code is a Liquid template. In the same way that a Shopify storefront might use a Liquid template to receive requests and render HTML, a task uses its Liquid code to receive events, and render a series of JSON objects. These JSON objects define actions, logs, and errors.

Task code always has access to a set of environment variables, which can be used to make decisions about what JSON objects to render.

A task must purposefully consider its preview, so as to accurately communicate its intent to users and to the Mechanic platform.

Shopify uses webhooks to notify apps like Mechanic about new activity. Mechanic supports every type of Shopify webhook in its set of Shopify event topics. By setting up subscriptions to these topics, a task may respond to any supported type of Shopify activity.

Responding to changes in specific data

Shopify's "update" webhooks do not contain information about what piece of data has changed. (For example, a product update webhook does not specify what attribute of the product has changed.) For this reason, it's not possible to subscribe to changes in specific resource attributes (like product SKUs, or order tags).

If a task needs to react to a specific attribute change, the task must scan for and "remember" the original value of that attribute, so as to compare incoming updates with that remembered value. A task could use the Cache action to store these values in the Mechanic cache, or it could use the Shopify action to save the remembered value in a metafield.

For an example implementation, see the Auto-tag products when their variants change task.

Shopify allows apps to inject JavaScript into the online storefront. (This is facilitated by ScriptTag in the Shopify API.)

Mechanic supports this by allowing each task to specify its own JavaScript, to be injected into the online storefront.

Here, the developer can add in their own JavaScript code, taking advantage of Liquid for mixing in data from the current store, or from the current task's options.

In specific cases, events may be triggered by activity associated with an earlier event. In these scenarios, we describe the subsequent event as a child event, and the preceding event as a parent event.

• The Event action generates a new child event, when performed

• A subscription to the mechanic/actions/perform topic generates new child events as actions are performed

Tasks responding to child events may reference to the parent's event using {{ event.parent }}. Parent events are recursively available (as in {{ event.parent.parent.parent }}), to a limit of 5 generations back.

When viewing any given event in Mechanic, look in the event details to find any parent or child relationships that apply. Click through to any displayed parent or child event to view that event's details.

Example

mechanic/user/trigger
user/fan/out

{% assign n = event.data | default: 0 | times: 1 %}

{% if n < 5 %}
  {% for m in (0..n) %}
    {% action "event" %}
      {
        "topic": "user/fan/out",
        "data": {{ n | plus: 1 | json }},
        "task_id": {{ task.id | json }}
      }
    {% endaction %}
  {% endfor %}
{% else %}
  {% action "echo", event_data: event.data, parent_event_data: event.parent.data %}
{% endif %}

As written, this task will "fan out": it will generate 1 child event, which will then generate 2 child events, each of which will then generate 3 child events, and each of those will then generate 4 child events, and finally, each of those events will generate 5 child events of their own. The result: 154 events, created with a single click. 💪

Importantly, note the "task_id" option, applied to the Event action. This option ensures that only this task, and no other, will respond to the new event. While it's unlikely that any other task will subscribe to "user/fan/out" events, this option is important for ensuring expected behavior.

In some cases, a run that has already been performed may be performed again, using a retry.

When a run is retried, its previous result is permanently discarded. Because of this, runs that already have a meaningful result (i.e. an event run that gave rise to task runs, or a task run that generated actions, or an action run that succeeded) cannot be retried.

Runs are given automatic retries when a non-permanent error is encountered. In some cases, Mechanic permits manual retries for runs, allowing users to reset a run's result and perform the run again.

Retry context

Retried event runs will always reflect Mechanic's current configuration, including any event filters.

Retried task runs will always use a task's latest configuration, including the task's options, code, and Shopify API version.

Retried action runs will always use their original action options, as dictated by the task run that generated them. Action runs are entirely unaffected by updates to their task.

Automatic retries

When non-permanent errors are encountered, Mechanic will automatically retry a run. For HTTP actions, this might be a connection error. For Email actions, this might be a temporary outage with our email provider.

Mechanic will automatically retry these runs up to 4 times, for a total of 5 attempts. Retries are subject to a variable backoff delay, of approximately 0:30, 1:16, 2:32, and 5:08 respectively, for each of the 4 retries.

Manual retries

Some task runs may be manually retried, via the Mechanic user interface.

Task runs

Task runs may be retried...

• ... if the task run itself failed (due to a Liquid error, an API error while reading data, or something else)

• ... or, if the task run did not generate any actions

During task development, it can be useful to set up a task to only render log objects. A task run which only rendered log objects can be retried, and this ability to retry can be convenient when rapidly iterating on task code.

Action runs

Only failed action runs may be retried.

The URL file generator accepts a string as its options, containing a valid URL. This generator downloads the file at that URL, returning the results.

Downloaded files may be a maximum of 20 megabytes, even when used within other file generators (like ZIP).

Options

This file generator accepts a string containing a valid HTTP or HTTPS URL. It does not support any other options.

{
  "url": URL
}

Example

{
  "action": {
    "type": "files",
    "options": {
      "image_from_url.png": {
        "url": "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"
      }
    }
  }
}

The plaintext file generator is used implicitly, when a JSON string is given in place of a standard file generator JSON object. The resulting file will contain the content of the string, with no further processing. This makes the plaintext generator suitable for text files, CSV files, TSV files, and any other file format that can be expressed using plain text.

The plaintext generator cannot be invoked explicitly; "plaintext" cannot be used as a named generator type.

Options

Because this file generator is used implicitly, when a string is given instead of a file generator object, this file generator does not use options.

Example

{
  "action": {
    "type": "files",
    "options": {
      "plain.txt": "This\nis\na\nmulti-line\nplaintext\nfile."
    }
  }
}

In this tutorial, you'll learn how to create a feed of your shop's data, and make it available on your online store, at a URL like https://example.com/pages/feed

Tip: The data you generate can be imported directly into Google Sheets. Learn more:

Instructions

1. Create your task.

Start with our example task, using the "Try this task" button to add it to your account:

Immediately after adding the task, run it by clicking the "Run task" button. This will populate your shop's records with the initial value of the feed.

This task replicates Shopify's own product inventory CSV export. Feel free to make changes to the script, and don't hesitate to get in touch if you have questions. :)

2. Create a page template, called "page.feed.liquid".

This is the template that will be responsible for displaying your feed contents, without the usual page formatting that your shop's theme usually applies.

To do this, navigate to the "Themes" section of your Shopify admin (under "Online Store", or by searching for "themes"). Then, under the "Actions" menu for your current theme, click the "Edit code" link.

Next, click "Add a new template".

Then, select the option for creating a "page" template, of type "liquid", and fill in the text box with the name "feed" (or another template name to your liking).

Next, fill in the template contents with the following:

... and click the "Save" button. Your template should look like this:

3. Create a new page to use as your feed.

Navigate to the "Pages" section of the Shopify admin (under "Online Store"), and click the "Add page" button (or search the admin for "add page"). Name the page "Feed" (or another name of your liking), and change the page template to "page.feed.liquid".

Save the page.

You're done!

Open up the page you just created, and you should see the contents of your feed. :) If you have any questions, head to .

Until further notice, Shopify will continue to send product webhook data in a REST-like format. Tasks that only use the fields available in the webhook (e.g. product.title) may not need to be converted by the deprecation notice date. However, if connections to other resources are made from that product (e.g. product.collections), then that will require conversion.

This is a simple task to loop through a product's collections, check if the collection contains a certain tag, then log out the collection title.

The GraphQL version of the the task above use a paginated query to get all of the collections a product is a member of. The outer loop upper range (e.g. the 10 in {% for n in (1..10) %}) is arbitrary, and you may adjust it to the approximate maximum number of collections any given product might have.

The event preview block in this task sample makes this code appear to be overly verbose, however the is often an important step to ensure that Mechanic prompts for the correct scopes for reading and writing Shopify API data.

For every Shopify resource object that supports metafields, Mechanic has traditionally provided a way to directly access those metafields from the resource using . This shortcut will no longer be accessible for product and variant REST resources once they are fully deprecated.

While metafields can be queried directly using their ID, this attribute is not present in the product webhook data. The standard approach in GraphQL is to query the product resource for the metafield(s) and value(s), passing the namespace and key as the "key" value, in the same manner as the REST dot notation lookup.

In Mechanic, a task is a bundle of logic and configuration, that responds to and interprets . The result of a task can define , which are the task's opportunities to have an effect on the world.

A task responds to events based on its . When an event is received that matches a subscription, the task processes the event using its . The code has access to the event data; it also has access to the user's task configuration, through . Task code is written in Liquid, and is responsible for rendering a series of JSON objects (including , , and objects), defining work to be performed once task rendering is complete.

A task uses its to communicate ahead of time the work it intends to do. Previews are important for users, and are also important for Mechanic itself – Mechanic looks to the task preview to understand what permissions a task requires.

Tasks may be written from scratch, or installed from the Mechanic library (available in-app and ). Once installed, a task's code may be modified at any time.

Example

This very basic task subscribes to shopify/customers/create, and renders an , using an email subject and body taken from user-configured .

A task subscription is the expression of a task's intent to receive certain , filtering by . A subscription consists of an event topic, optionally combined with a time offset, which creates a delay.

A task may have any number of subscriptions.

Delays

... are accomplished using subscription offsets, as described below. This heading is here for folks searching for a way to delay their tasks. ;)

Offsets

A subscription offset (sometimes called a delay) defines the amount of time a task should wait or delay (!!) before responding to the incoming event. It's the easiest way to add a delay to a task's subscription to a specific topic. (For finer control over event timing, try using the run_at option of the .)

Subscription offsets are appended to the subscription topic, and are of the form "+1.hour". Offsets may be given using seconds, minutes, hours, days, weeks, months, or years. There is no limit to how large the subscription offset may be.

A subscription with an offset looks like shopify/customers/create+1.hour.

To learn more about scheduling work with Mechanic, see .

Using Liquid

A task's subscriptions are parsed for Liquid, at the time the task is saved. Combined with , this is an opportunity to generate subscriptions based on user configuration, adding or removing subscriptions based on the user's choice, or adjusting subscription offset based on a user-entered value.

One subscription is permitted per line. Blank lines and leading/trailing whitespace are permitted.

Examples

In general, Mechanic's system does not guarantee the execution order for runs that have been created at the same time (see ). This applies to all kinds of runs: events, tasks, and actions.

For tasks, the simplest way to manage this is by using subscription delays, offsetting the time at which each task is run. For example, if you have two tasks that subscribe to shopify/customers/create, you might adjust one so that it it subscribes to shopify/customers/create+10.minutes instead. This way, your first task has a chance to execute and run before the other.

This is not a perfect solution: naturally, if the first task takes more than 10 minutes to run, there will still be overlap. So, Mechanic makes

Guaranteeing run order for actions

Each task has an advanced option called "". When this is enabled, all generated actions for a given task run will be executed precisely in order.

Guaranteeing run order for tasks

The best tool to leverage here is the , coupled with action sequences (see above).

1. Begin by making a list of the tasks for which you need to guarantee run order, sorted by the desired run order. For these purposes, all of these tasks should subscribe to the same event topic.

2. Beginning with the task that should run first, (a) enable "Perform action runs in sequence", and (b) add an "event" action at the very end of your task script. The intent here is for this action to kick off a unique event topic that the second task should the subscribe to.

3. Having added that "event" action, update the second task so that it subscribes to your new event topic, instead of the original event topic. If there is a third task that should follow this one, repeat step 2 for this task as well, in preparation for kicking off the third task.

4. Repeat until you reach the final task in your list. This task does not need an "event" action at its conclusion; it only needs to have its subscription updated to listen for the penultimate task's generated event.

One more tool is worth mentioning: tasks may subscribe to mechanic/actions/perform to be re-triggered when each of their own actions are performed. For more on this strategy, see .

In general, Mechanic will process as many simultaneously as possible. This means that multiple tasks subscribing to the same event topic are very likely to execute simultaneously, when such an event occurs.

To protect the health of the system and to ensure performance for every store on the platform, Mechanic have several concurrency limits, defining the conditions in which Mechanic will perform runs simultaneously.

Limits

Each store's Mechanic account has a fixed run queue size. This limit controls how many runs Mechanic will perform simultaneously for your store. With a limit of 2, this could mean 2 events, or 2 tasks, or 1 event and 1 tasks and 0 actions, or any other combination of runs. Additional runs will be performed as the preceding runs complete.

Tips

• Use GraphQL to query Shopify, to keep your data usage efficient. (To learn more, see .)

• For options for ordering execution of runs, see .

A typical REST products loop in Mechanic will have the structure below. While this is a concise format to get all products in shop, its main drawback is the inability to limit or filter the number of records and fields returned. This generates a significant amount of extra data for the task to manage in memory during a task run, especially if connected resources are looped as well (e.g. variants).

{% for product in shop.products %}
  {% comment %}
    -- product processing here, using REST fields
  {% endcomment %}

  {% for variant in product.variants %}
    {% comment %}
      -- variant processing here, using REST fields
    {% endcomment %}
  {% endfor %}
{% endfor %}

GraphQL paginated queries work by using the same (potentially filtered) query repeatedly to retrieve resources until the end of the list is reached or the querying is terminated by code logic. In Mechanic, paginated queries are typically implemented by using an outer "for loop", with an arbitrary number of maximum loops (e.g. the 100 in {% for n in (1..100) %}). Within the query itself, the first filter limits the number of records returned in this batch, and the after filter will instruct which "cursor" the query should start at. This cursor will initially be set to nil, which indicates starting at the beginning, and it will be updated by the looping logic before the next query is run, using {% assign cursor ... %}.

Finally, the query filter of a resources query gives the ability to drastically reduce the number of records returned, allowing for very targeted inclusion and exclusion rules (e.g. products having a certain tag). Each resource has its own list of query filters, which can be reviewed in the GraphQL Admin API docs

{% assign cursor = nil %}
{% assign search_query = nil %}

{% for n in (1..100) %}
  {% capture query %}
    query {
      products(
        first: 250
        after: {{ cursor | json }}
        query: {{ search_query | json }}
      ) {
        pageInfo {
          hasNextPage
          endCursor
        }
        nodes {
          id
          # relevant product fields
          variants(first: 100) {
            nodes {
              id
              # relevant variant fields
            }
          }
        }
      }
    }
  {% endcapture %}

  {% assign result = query | shopify %}

  {% if event.preview %}
    {% capture result_json %}
      {
        "data": {
          "products": {
            "nodes": [
              {
                "id": "gid://shopify/Product/1234567890",
                "variants": {
                  "nodes": [
                    {
                      "id": "gid://shopify/ProductVariant/1234567890"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    {% endcapture %}

    {% assign result = result_json | parse_json %}
  {% endif %}

  {% for product in result.data.products.nodes %}
    {% comment %}
      -- product processing here, using GraphQL fields from the query
    {% endcomment %}

    {% for variant in product.variants.nodes %}
      {% comment %}
        -- variant processing here, using GraphQL fields from the query
      {% endcomment %}      
    {% endfor %}
  {% endfor %}
  
  {% comment %}
    -- if there is another page of data, then update the cursor for the next loop
  {% endcomment %}

  {% if result.data.products.pageInfo.hasNextPage %}
    {% assign cursor = result.data.products.pageInfo.endCursor %}
  {% else %}
    {% break %}
  {% endif %}
{% endfor %}

To see a code diff from a Mechanic library task that was recently converted in this manner, click here.

Event and task runs may be scheduled to perform in the future. They will not have any effect until they are performed. This means that their eventual performance may be impacted by changes to a store's Mechanic account, prior to the scheduled performance time.

Event runs

The Event action

Event runs may be scheduled using the Event action, using its run_at option to define the time at which the run should be performed.

The task runs that arise from a scheduled event run will not be established until the event run is performed. (This does not apply if the task_ids option is used, which determines ahead of time which tasks may be run in response to the new event.) This means that changes to the set of enabled tasks can have an impact on what tasks are actually run, in response to a scheduled event run.

Scheduler events

Mechanic supports several scheduler topics (such as mechanic/scheduler/hourly), allowing tasks to be automatically invoked by the platform on a regular repeating interval.

Event runs generated in response to scheduler events are always adjusted for the store's local time.

Task runs

Subscription offsets

Task runs may be scheduled using subscription offsets, in which a task states that it wishes to run later (by some amount of time) than the event that triggers it.

Subscription offsets are a property of the task, and are applied by the task run – not the event run. This means that the subscribed-to event must be created and run before the subscription offset is calculated and applied.

The Event action

To achieve precise scheduling (e.g. "run on December 16th at 2:30pm"), or to accomplish scheduling for an interval not supported by Mechanic's scheduler topics, use the Event action to schedule an event run at any chosen time, with a custom event topic. Make sure that the desired task is subscribed to the same custom topic, and consider using the Event action's task_id option to specify that only the desired task is allowed to respond to the new event.

Task runs that are scheduled for the future will always use a task's latest configuration, including the task's options, code, and Shopify API version.

If a task is disabled or deleted at the time a task run comes due, the task run will still perform at the scheduled time, but will fail instantly.

To make events easy to identify, each event has a topic. Tasks signal their interest in specific event topics using subscriptions.

A topic looks like "shopify/customers/create", and it has three parts:

• The domain describes the source of the event. Shopify events have "shopify" as their domain, and events generated by Mechanic itself use "mechanic".

• The subject describes the type of resource the event describes. Events that are about customers have "customers" as their subject, and events that are about orders have "orders".

• The verb describes what has just occurred. Events that are about creating resources generally have "create" as their verb, and events that are about deleting resources generally have "delete".

User-defined topics

The User event domain is for custom, user-generated events, having any subject and verb (e.g. "user/foo/bar"). As with all events, a User event topic must use the standard three-part topic form, but only the "user/" prefix is mandatory.

Mechanic allows developers several ways to generate custom User events:

• The Event action can be used with any User event topic

• Webhooks may be configured to generate events using any User event topic

The Shopify action allows developers to submit any request to the Shopify Admin API. By responding to action results, the data returned by Shopify can be retrieved, and re-used by the calling task.

This approach should (probably) only be used as a last resort, when Mechanic's other methods of reading data do not cover the scenario.

Mechanic's task library is a central resource for the entire community, and is continually enriched through contributions, via pull requests on GitHub.

Contributing your work to the task library

You've created a custom task, and you want to share it with the world! This brings us so much joy, and this is what the Mechanic project and this community are all about. If you get stuck along the way, please hop onto the Slack workspace, and we'll be glad to help.

We follow the same process any open-source project does when it comes to code management and code contributions. One bonus of contributing to the Mechanic task library is that once you learn the process here, you'll know how to contribute to open-source projects going forward.

The process

• You'll fork the task library repository.

  • Forking means taking a copy of our repository, so that you can make your changes and additions.

• Make your changes in your forked repository.

• Make a pull request, which will trigger a review of your proposed changes and the merging of them into the main repository, making your task available to everyone using the app.

Step-by-step instructions

1. You'll need a GitHub account, you can signup for one here.

2. Visit the task library repository and fork it as shown below. You'll make your changes to this copy of the repository.

3. The task library is made up of the tasks and the supporting documentation. In these next few steps, you'll ensure you can build the docs, so that you can complete this step when you are ready to submit your contribution.

   1. Building the docs requires nodejs and npm. You can install them from here: https://www.npmjs.com/get-npm

   2. While in the project directory, run the following commands to build the docs:

   Copy

   npm install   # install dependencies
   npm run build # compile docs
   npm run test  # apply sanity checks

4. Now that you can build the docs you are ready to contribute!

5. Your task documentation, options, subscriptions, code, are done in Mechanic. If you choose to use an external editor that's great, you still need to transfer it into Mechanic, so that you can export the task in the JSON format you need for the library. Importing/Exporting tasks from Mechanic is covered here.

6. If you're changing an existing task you export the JSON, and replace the contents of the task/task_file_name.json and then run the commands npm run build and npm run test.

7. If you are contributing a new task, you'll export the JSON from Mechanic, and save the JSON file in the tasks/directory of your forked repository, named with an appropriate handle for the task. (For example, a task named "Hide out-of-stock products" should have its JSON export stored in "tasks/hide-out-of-stock-products.json".) And, then you'll execute the commands:

   npm run build and npm run test.

8. If all goes well with the build, you'll see your task listed in the automatically created documentation in docs/README.md

9. You're now ready to make your pull request! Head over to https://github.com/lightward/mechanic-tasks/pulls and click New pull request, you should see the changes you committed to your fork, and you'll proceed with filling out the pull request form.

10. After you submit your first pull request, you will be required to read and accept our CLA. The CLA assistant will leave a comment, giving you a statement of agreement that you must paste into a comment of your own.

11. This process could sound confusing if you haven't done it before, but once you've done it once, it's simple and it is also pretty exciting to go through the process. The other bonus is, you'll be ready to submit a pull request to any open-source software project in the future. If you need help please out to us in the community Slack workspace.

Webhooks are the nearly ubiquitous carriers of information to and from services across the internet - services like IFTTT, Zapier, Stripe, PayPal, JotForm, and countless more. You can use webhooks to send information from these services into Mechanic, where you can then perform any logic and actions you need.

When Mechanic receives data via a webhook, it fires off an event with the user topic of your choice. (For example, if you've set up an IFTTT webhook that sends you tweets, you might choose the Mechanic topic user/ifttt/tweet.) To make use of these events, create one or more tasks that subscribe to this topic. That's it!

Let's review a detailed example.

1. Create a Mechanic webhook.

Start by opening Mechanic, from the "Apps" section of Shopify. Once in Mechanic, click the "Settings" button in the upper-right corner, then navigate to the "Webhooks" tab.

Webhooks should be named after the service that will be sending you data, with an event topic that makes sense, using the format user/subject/verb.

For this example, we'll simply call ours "Example", with an event topic of "user/webhook/test".

Click the submit button to save the webhook, and use the copy button to copy the resulting webhook URL.

The URL will look something like this:

https://webhooks.mechanic.dev/00000000-0000-0000-0000-000000000000

2. Create a task that subscribes to your webhook event.

Back on the Mechanic homepage, click the "Add task" link.

Then, click the "Start a blank task" button.

Keeping things simple for this example, we'll title the task "Webhook test", with a subscription to "user/webhook/text" (to match the webhook configuration), and a simple Echo action in the task code.

Lastly, save the task.

3. Test your webhook.

Open https://reqbin.com/, and construct a request to our webhook. Here, we'll select "POST", paste in the webhook URL, and fill in a simple piece of content. (Webhooks support plain text, form-encoded content, and JSON; for this example, we'll use JSON.)

Click the "Send" button, and you'll see a 204 response returned within ReqBin.

Over in Mechanic, watch for the new event on the "Events" page (or in the "Recent events" section of the Mechanic homepage):

Click on that event to see the results of our task and its echo action.

4. Connect your webhook URL to another service.

This last part is up to you! Provide the webhook URL, generated by Mechanic, to whatever service you'd like to use. When provided with this URL, the service will start sending your data over to Mechanic for processing.

That's it! :) Adjust to taste.

The ZIP file generator accepts an options object, specifying a set of files (themselves defined using file generators) to be compressed into a single ZIP file. The resulting ZIP file may optionally be password-protected.

Options

{
  "zip": {
    "files": FILENAMES_AND_FILE_GENERATORS,
    "password": PASSWORD
  }
}

Example

{
  "action": {
    "type": "files",
    "options": {
      "secure.zip": {
        "zip": {
          "password": "opensesame",
          "files": {
            "confirmations.txt": "this data is protected with zipcrypto encryption",
            "image.png": {
              "url": "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"
            },
            "receipt.pdf": {
              "pdf": {
                "html": "<h1>!!</h1>"
              }
            }
          }
        }
      }
    }
  }
}

The Shopify API supports versioning for their REST and GraphQL admin APIs. (Learn more: shopify.dev/api/usage/versioning.)

Each Mechanic task has an individually-configured Shopify API version, defaulting to the latest stable version at the time of the task's creation. A task's version will apply to all Shopify API calls generated by its task code, in addition to all calls performed by that task's actions.

Each stable Shopify version is supported for one year. 30 days before a version ends support, tasks on that version will be silently upgraded to the next stable version. As a consequence, versions that are unsupported (or are within 30 days of no longer being supported) are not available in Mechanic.

Task usage

Deprecations

Every quarter, Shopify releases a new version of the Admin API, and simultaneously removes the oldest version of the admin API. (Subsequent calls to removed APIs will be responded to by the oldest still-supported version.)

As Shopify prepares to pull support for specific API calls, deprecations are announced, and are communicated in API responses.

Learn more about Shopify's deprecation practices

Identifying deprecations

If support for a task's Shopify API version will be pulled soon, its deprecations will be shown above the main task list.

Deprecation details are available in the advanced task editor, in the Runtime tab.

Resolving deprecation warnings

Deprecation warnings can be dismissed by doing one of the following:

• Selecting a new Shopify API version for the task

• Updating the task script

• Disabling the task

• Deleting the task

Mechanic has native awareness of Shopify's Admin API rate limit, and will accordingly manage the execution of operations that require access to the Shopify API. Mechanic users do not need to manage the API rate limit themselves.

If the rate limit has been reached, any due task runs or Shopify action runs will wait to be enqueued until the rate limit has recovered.

If the rate limit is reached during a run's performance, Mechanic will automatically wait and retry any affected API queries until they succeed, up to a certain number of retries. If the API rate limit does not recover in a reasonable amount of time, Mechanic will raise a permanent error for the run.

Optimizing API usage

Query efficiency

When querying for data within a task, use GraphQL whenever possible, rather than using Liquid objects. GraphQL is much more resource-efficient, and usually results in greater operational throughput.

When working with large volumes of data, use a bulk operation. This way, Shopify bears the burden of collecting all relevant data, without in any way playing against the Shopify API rate limit for Mechanic.

Task configuration

Keep an eye on tasks that are running at the same time, competing for resources. The Shopify API rate limit is shared across each store's entire Mechanic account, which means that simultaneously-running tasks may be in competition for Shopify API usage. Adjustments to task timing (possibly using subscription offsets) can be useful, when making sure that tasks aren't competing. And, in some cases, it may be useful to decrease the overall concurrency limit for a Mechanic account, by emailing [email protected].

Shopify Plus

In high-volume scenarios for Shopify Plus accounts, Mechanic's performance can be improved by creating a custom Shopify app, having the same permissions that you've granted to Mechanic. Because this private app represents your explicit control and intent, it usually comes with a higher API rate limit. (And, in some cases, Shopify can grant this custom app a higher API usage limit, upon request.) By providing Mechanic with this custom app's Shopify Admin API access token, you can extend this higher limit to Mechanic.

This feature is also useful for accessing Plus-only APIs, which are only available to custom Shopify apps. Notably, this includes gift cards (using the gift card object).

This setting can be found in the Mechanic account settings, in the Permissions area. (This setting is only shown for Shopify Plus accounts.) Before adding your API token, you must ensure that the private app has every access scope that Mechanic requires. A list of current required access scopes is provided just below the token field.

Once configured, this custom API token will be used for all user-configured Shopify operations, wherever supported. (It will not be used when querying for publications, since this resource is only accessible to public apps like Mechanic.)

During , Mechanic scans the task's . For each found, Mechanic constructs a synthetic preview event, resembling one that the task might encounter during live use.

By default, each preview event's data is sampled from previous events that the Mechanic account has seen, for the same topic.

However, developers may define their own preview events, containing whatever data the developer wishes to use for preview. This may be useful for several reasons:

• Most tasks conditionally respond to events based on their data. Controlling the event data present during preview allows the developer to deterministically verify the results of the action.

• Further, by deterministically/predictably generating actions, the developer can consistently demonstrate the permissions they need to Mechanic. (To learn more about this, see .)

• Defining preview event data is usually simpler than defining .

  • Stubbing the event variable (or any of the ) removes any intelligence from the objects Mechanic generates from event data, a drawback avoided by defining a preview event and its data. Using the as an example, a task may typically access its custom attributes via order.note_attributes.color, or via order.note_attributes[0].value. This dynamic behavior is lost if the event variable is stubbed out, which can result in behaviors that are difficult to diagnose.

• Multiple preview events may be defined per event topic. This allows developers to verify that their task renders the appropriate results under a variety of circumstances.

  • Defined preview events can be labeled with a description, which is visible in the task preview pane. This makes it easy to identify the scenario that a preview event is meant to represent.

Configuration

Preview events may be defined using the "Edit preview events" button, in the task preview pane.

The configuration area for preview events contains a quickstart link for each event topic the task subscribes to, allowing developers to get started using sample data if the event topic is known to Mechanic. Or, the developer may start with a blank preview event definition, filling in whatever topic and data are useful.

A developer may define any number of preview events per topic. If no preview events are defined for a given topic, Mechanic will construct its own ad-hoc event during preview.

Properties

Description

Displayed beneath the event topic in the preview pane, allowing the developer to distinguish one scenario from another.

Topic

Identifies the event definition to Mechanic, when Mechanic goes to construct preview events by topic.

Data

Used to construct event.data, and may be set to whatever values are useful in representing a specific scenario. The data structures used here should resemble what Mechanic will receive for a live event of the same topic.

Notably, the data here can be limited to just the properties that are useful. For example, while Mechanic might normally generate a complete payload for shopify/orders/create, the developer might only care about the "email" property of the order – and so their defined preview event data might be limited to just that property. (Note that the inverse may not be true: defining preview event data for traversals into other objects, e.g. using preview event data to define a value for order.line_items[0].product.title, will not work.)

Example

For a trivial task, subscribing to shopify/customers/create, and having the following task code...

... we define two preview events, one which represents a Gmail user, and one which does not. This allows us to easily assert that the task behaves properly in both scenarios.

Versioning

Preview event definitions are stored along with the task itself, and thus are present in the tasks version history (and, naturally, in task exports).

Because definitions are a part of the task itself, they're appropriate for use as a testing tool, allowing the developer to verify that a task behaves as intended at every stage of the task's development.

A task's Liquid code always has access to a set of environment variables, defined by Mechanic.

Event subject variables

When a task is actually invoked for an event, it may have access to an additional variable, determined by the specific event it is responding to. When this is the case, the additional variable will be named after the event subject, and its contents will be established by the event's data. The name of this variable is communicated by the Mechanic task editor, based on the task's current .

For example, a subscription to shopify/customers/create will make available a variable called customer. A subscription to shopify/products/update will expose a variable called product, etc.

Shopify variables

All Shopify events support an additional variable named after the event topic. For example, when a task responds to a shopify/customers/create event, it will have access to an additional variable named customer, containing the customer data contained in the event.

Shopify events always contain data from Shopify's REST representation of each resource; therefore, automatic Shopify variables always contain data from the REST representation as well. The best resource for the data available for each variable type is .

The Echo action has no effects: it returns the options that are given. This action can be useful for testing or debugging, by temporarily replacing some other action with an Echo action having the same options. In this way, a developer can safely get feedback on what data is in play, without side effects.

Options

This action accepts any and all options, restricted only in that they must be valid JSON values (as with all results of ).

Forcing an error

If the Echo action is given a "__error" option, it will raise that error when the action run is performed. Use this feature when it's useful to indicate an issue with a task run, without marking the entire task run as a failure (as would be the case when using an ).

Examples

In Mechanic, an action is an instruction for performing work that has an effect. Actions are generated by , in response to . Each action has a type, specifying the class of operation to be performed, and options, providing specifics about what that operation will do.

Actions are defined by tasks using , which are simple JSON objects specifying an action's type and options. Action objects can be constructed using the .

Action types

An action type determines the class of operation to be performed. While actions may vary greatly, there are only a few action types.

Integrations

Mechanic maintains a set of integration actions, offering first-class support for several external services.

The Cache action allows developers to interact with the store's Mechanic , using commands inspired by Redis. Cache entries have a key, a value containing up to 256 kilobytes, and a ttl value ("Time To Live") in seconds, defaulting to the maximum of 60 days (i.e. 5184000 seconds).

Options

This action supports two styles of options: a more verbose nested structure, and a simpler set of positional arguments.

All commands must define a cache key, matching the regular expression /^[a-z0-9_:\-\.\/]+$/i.

Verbose options

In this option style, the cache command is given as the root key of the options object. The root value is itself an option, containing the arguments needed for the selected cache command.

Positional options

In this option style, the cache command and its arguments are given in a list. Use the cache command reference below to find the argument order required for each command.

Expiration

Each cache entry is given a default TTL value of 60 days, or 5184000 seconds. (A cache entry's TTL may not exceed 60 days.)

A cache command will always reset the entry's TTL value upon execution, regardless of the TTL's original value.

Commands

The required arguments for each command are given below, in the order in which they are supported for .

When a command is given using , the ttl value (in seconds) is always supported.

set

Stores a value. Requires key and value. The stored value may be any JSON object.

setex

Using a defined TTL (an expiration interval) given in seconds, stores a value. Requires key, ttl, and value. The stored value may be any JSON object.

del

Deletes a stored key. Requires key.

incr

Increments a numeric key by 1. Requires key. If the key is not already set, the value before incrementing will be assumed to be 0.

incrby

Increments a numeric key by the value of your choice. Requires key, and an integer increment. If the key is not already set, the value before incrementing will be assumed to be 0.

decr

Decrements a numeric key by 1. Requires key. If the key is not already set, the value before incrementing will be assumed to be 0.

decrby

Decrements a numeric key by the value of your choice. Requires key, and an integer decrement. If the key is not already set, the value before incrementing will be assumed to be 0.

Examples

Set a value, auto-expiring in 60 days

Set a value, explicitly expiring in 1 minute

Clear a value

An action object defines work to be performed by an , after the task is fully finished rendering. Action objects are most easily generated using the .

An action object is a plain JSON object, having the following structure:

Defining an action

Type

The action type is always a string, having a value that corresponds to (e.g. "shopify", or "http").

Options

Action options vary by action type. Depending on the action type, its options may be another complete object, or an array, or a scalar value.

Meta

Actions may optionally include meta information, annotating the action with any JSON value.

This information could be purely for record-keeping, making it easy to determine why an action was rendered, or to add helpful context:

Or, this information could be used to facilitate complex task flows, in concert with a subscription to mechanic/actions/perform (see ). An action's meta information can supply followup task runs with information about state, allowing the task to cycle between different phases of operation.

, , and are all processed using queues, in which a piece of work is enqueued, and performed in its turn. Each piece of work is called a run. Thus, Mechanic performs work using event runs, task runs, and action runs.

When performed, a run has a result. Depending on the type of run, this result may define additional runs to be performed after it concludes.

• Event runs, when performed, may result in a set of enqueued task runs.

• Task runs, when performed, may result in a set of enqueued action runs.

• Action runs, when performed, have behaviors that vary by .

  • If the originating task , each action run will spawn a new event containing that action's results. This new event will be processed in an enqueued event run, creating an opportunity for the task to respond to the action's results.

Most runs are scheduled to be performed immediately. Some runs may be for the future. Some runs may be , once performed.

At the moment a run is performed, it loads in all related data (which may include the related store, or the related event, or the related task).

Run flow

A normal flow in Mechanic looks like this:

1. An event is created – possibly by a , or by a , by the , or by an .

2. An event run is created, and performed. During this phase, Mechanic scans the store's tasks to see which ones are relevant for the current event, by checking the subscriptions on file for each task. For each task that Mechanic discovers for the event, a task run is created. (If the task subscription involved an , as in mechanic/scheduler/daily+2.hours, the task run will be set to wait for that amount of time.) The result of the event run is this set of task runs.

3. Each task run is performed. During this phase, Mechanic takes each task's , and renders it using the associated event. The result of the task run is the set of JSON rendered by the task's Liquid code. Each action object is used to create an action run.

4. Each action run is performed. During this phase, Mechanic executes each action, given the options that were provided for it by the task run's result.

Understanding this sequence of events is important. Task runs do not come into existence until the event run has been performed, and action runs are only performed after their task run has fully concluded.

Critically, this means that tasks do not have direct access to the effects of the actions they generate. Actions are performed later in the sequence, and their effects will only be seen by subsequent task runs.

Run priorities

In general, given a mix of event, task, and action runs that are all due, Mechanic will perform due action runs first, then due task runs, and finally due event runs.

If Shopify's rate limit for either the GraphQL or REST Admin API has been reached, Mechanic will skip over task runs and over runs, until both rate limits have been recovered. In these cases, Mechanic may choose to perform due runs of a lower priority, while it waits for the Shopify API rate limits to recover sufficiently to perform the higher priority runs.

Run states

The Mechanic community maintains a board of task requests, where anyone can submit their idea for an addition to the Mechanic task library.

What kind of task requests are accepted?

We accept task requests in two categories:

• Tasks that are broadly useful off-the-shelf for non-technical users

• Tasks that are useful foundations for developers, for further modification or inspiration

Who implements these task requests?

The Mechanic staff commission these from developers in the Mechanic community. If you're a developer interested in receiving this kind of work, get in touch at .

Where can I file a task request?

Head to . :)

The Files action evaluates its options using file generators, temporarily storing the resulting files and making them available via a randomized Mechanic URL.

This action is most useful in concert with mechanic/actions/perform, by which a task may take the resulting file URLs and pass them on to another service. Used by itself, this action can also be useful for quickly testing file generators.

Options

This action accepts a JSON object, whose keys are filenames and whose values are file generators. In this way, many files may be defined and generated by a single Files action.

Result

A Files action returns an object having the same keys (i.e. filenames) as its input. Each value is an object, having the following properties:

Example

This task generates a variety of files. It then re-invokes itself (via mechanic/actions/perform), sending an email containing links to each of the generated files.

mechanic/user/trigger
mechanic/actions/perform

{% if event.topic == "mechanic/user/trigger" %}
  {% action "files" %}
    {
      "journal.txt": "hello world!",
      "table.csv": "Title,SKU\nRed T-Shirt,TEE-R",
      "invoice.pdf": {
        "pdf": {
          "html": "<h1>Order #12345</h1>\n<p>It's due!</p>"
        }
      },
      "secure.zip": {
        "zip": {
          "password": "opensesame",
          "files": {
            "confirmations.txt": "this data is protected with zipcrypto encryption"
          }
        }
      },
      "external.jpg": {
        "url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
      }
    }
  {% endaction %}
{% elsif event.topic == "mechanic/actions/perform" and action.type == "files" %}
  {% capture email_body %}
    <p>The following file(s) have been generated:</p>
    <ul>
      {% for keyval in action.run.result %}
        {% assign filename = keyval[0] %}
        {% assign file = keyval[1] %}
        <li><a href="{{ file.url }}">{{ filename }}</a> ({{ file.size }} bytes)</li>
      {% endfor %}
    </ul>
    <p>-Mechanic</p>
  {% endcapture %}

  {% action "email" %}
    {
      "to": "[email protected]",
      "subject": {{ action.run.result | size | append: " file(s) generated" | json }},
      "body": {{ email_body | json }}
    }
  {% endaction %}
{% endif %}

File generators are invoked by actions to create new files, using options provided by the action, and handing the resulting file back to the action for further use. In this way, tasks can make choices about what files to generate, and what to do with the results.

Maximum filesize

Generated files may each be a maximum of 20MB.

Object structure

File generator objects, like action objects, are plain JSON objects each having a single key, and a single value. The object key specifies which file generator is to be invoked; the object value contains the options used for that generator.

{
  FILE_GENERATOR_TYPE: FILE_GENERATOR_OPTIONS
}

In practice, file generator objects are given as values in a larger JSON object, in which filenames are mapped to file generators.

In the following example, a Files action is defined, mapping filenames ("invoice.pdf", "external.jpg", and plain.txt) to file generators (a PDF generator, a URL generator, and – implicitly – a plaintext generator). Note how the file generator invocation varies, based on the specific file generator in play.

{% action "files" %}
  {
    "invoice.pdf": {
      "pdf": {
        "html": "<h1>Order #12345</h1>\n<p>It's due!</p>"
      }
    },
    "external.jpg": {
      "url": "https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg"
    },
    "plain.txt": "This\nis\na\nmulti-line\nplaintext\nfile."
  }
{% endaction %}

Supported actions

These are the Mechanic actions that support file generators.

Each task is configured with a specific Shopify API version, defaulting to the latest version at the time of the task's creation.

This version is used in all activity related to the current task, including:

• REST API calls performed to support Liquid lookups

• GraphQL calls performed by the shopify Liquid filter

• All Shopify API calls performed by the Shopify action, including bulk operations

Using "unstable"

All Shopify API versions are named with a specific date (i.e. "2021-07"), except for "unstable". This version receives regular updates from Shopify, and its features may change without notice.

Most tasks should use a dated version, to maximize the amount of time a task can rely on a specific set of Shopify API features.

Automatic version upgrades

Shopify supports each version for 12 months (except for "unstable", which is always available). 30 days before a task's version becomes unsupported, Mechanic will automatically begin calling the closest supported version instead.

Shopify may, at times, mark certain API features as deprecated. If a Mechanic account calls a deprecated API, Mechanic will display the deprecation notice in the app. Learn more about Shopify API deprecations.

Changing versions

The selector for a task's Shopify API version is available in Advanced mode, below the task code area.

An oft utilized feature of Mechanic is the ability to add Liquid tags into task options fields, such as a configurable email body. Additionally, these Liquid tags (currently) support inline resource lookups for data not available in the event webhook. However, for products and variants this will no longer work as of the Feb 1, 2025 REST deprecation date.

{%- assign qualifying_product = nil -%}

{%- for line_item in order.line_items -%}
  {%- if line_item.product.product_type == "Special" -%}
    {% assign qualifying_product = line_item.product -%}
    {%- break -%}
  {%- endif -%}
{%- endfor -%}

{%- if qualifying_product != blank -%}
  Special product notice for {{ qualifying_product.title }}...
{%- endif -%}

The code above could be utilized directly in a multiline task option field. and it would output a string of text (e.g. "Special product notice for Widget - Red...") into the assigned option field variable.

One method of conversion for lookup fields is to utilize a GraphQL query directly in the option field, which naturally has some caveats.

{%- assign order_id = order.admin_graphql_api_id | default: "gid://shopify/Order/12345" -%}

{%- capture query -%}
  query {
    order(id: {{ order_id | json }}) {
      id
      lineItems(first: 250) {
        nodes {
          id
          product {
            title
            productType
          }
        }
      }
    }
  }
{%- endcapture -%}

{%- assign result = query | shopify -%}

{%- assign qualifying_product = nil -%}

{%- for line_item in result.data.order.lineItems.nodes -%}
  {%- if line_item.product.productType == "Special" -%}
    {% assign qualifying_product = line_item.product -%}
    {%- break -%}
  {%- endif -%}
{%- endfor -%}

{%- if qualifying_product != blank -%}
  Special product notice for {{ qualifying_product.title }}...
{%- endif -%}

It can be helpful when using a GraphQL query in a task option field to add the code flag to the option field, which will add line numbers and give access to Mechanic code snippets.

{% assign email_body = options.email_body__multiline_code_required | strip | newline_to_br %}

Mechanic's run system works asynchronously, performing as much work as possible, as quickly as possible. However, there are cases where it's important that actions run in a sequence – one after the other.

We support this with an advanced task setting called "Perform action runs in sequence", configured in two parts:

• Perform action runs in sequence – When enabled, Mechanic will only run one of the task's resulting actions at a time, performing them in the order in which they were generated.

• Halt the sequence when one fails – When this option is also enabled, Mechanic will only run the next action if the current action was performed successfully. If the action fails, all following actions will be marked as failed as well, with error messages explaining the situation.

Tasks may use the to convert GraphQL query strings into simple result objects, by sending the query to the . The easiest way to build these queries is via the , which allows queries to be interactively constructed.

Usage

The accepts a GraphQL query string, and returns everything back from Shopify's GraphQL admin API. This means that reading back GraphQL data is as easy as this:

If you're working with multiple pages of data, you might use set up a forloop, using a cursor to retrieve page after page:

The hardest part of using GraphQL in Mechanic is writing the query itself. :) For help with this, we recommend installing . It provides an environment where, using auto-complete and built-in documentation, you can rapidly build the right query for your task.

Note: GraphQL queries (excluding whitespace) are limited to 50,000 characters. That's a hard limit, enforced on Shopify's end – if you bump up against it, you'll need to adjust your query strategy to always stay under that limit. If you're saving large values to a metafield, for example, consider separating those values using GraphQL variables, keeping the query itself trim. Learn more about this scenario using the , or with the .

Use GraphQL when...

• ... you want to make things more efficient. GraphQL is fantastic for being really precise about what data you want, which makes your tasks run in less time: no more looping through collections to find your data, and no more downloading data you don't require.

Don't use GraphQL when...

• ... it's easier and more readable to use Liquid objects, unless performance becomes an issue. Ultimately, the most important thing is that your task works well tomorrow – and that includes making sure that whoever works on it next understands what you're doing. If that means using a quick-and-simple Liquid lookup over a moderately-more-complex GraphQL lookup, go for it.

• ... you find yourself staring at nested loops. Looping through all orders is one thing – it's quite another to loop through pages of orders and loop through pages of line items within each order. For those scenarios, whenever possible, use a bulk operation.

Mechanic-flavored Liquid comes with a complement of , each of which is tied to a resource in the . Many objects support access to related objects via lookups (e.g. {{ shop.customers[customer_id].orders.first }}); in this way, the REST API can be traversed by resource.

Access to these Liquid objects varies, based on the context in which Liquid is rendered. For example, a task that subscribes to shopify/customers/create will have access to the object in its code, via a variable called customer. To learn more about how these objects are made available to task code, see .

Usage

Each task is given a set of to work with, out of the box. Mechanic's task code editor will tell you which ones are available. For example, for a task responding to a shopify/orders/ event, you might see this:

The , , , and objects are always available for tasks; the object (as in this example) contains the order to which the current event relates.

When a task renders an error object, the task run will be marked as failed, and no rendered action runs will be performed. This is a good way to communicate an intentional failure to the user, when your Liquid code detects a certain condition.

A task that renders an error object will interrupt the preview, and visibly communicate the error to the user. This makes error objects a useful way to validate .

An error object is a plain JSON object, having the following structure:

The error details can be any JSON value. This value will be represented to the user as the reason for the task failing.

Error objects are most easily generated using the .

There is a single correct answer for writing data to Shopify: the action. :)

Mechanic supports Shopify's bulk operations GraphQL API, allows developers to submit a query to Shopify for asynchronous processing, and making the results available to the task once complete.

This approach dodges the issues inherent in synchronous methods of reading data (like GraphQL via the shopify filter, or REST via Liquid objects). Unlike these methods, the bulk operations API does not exhaust Shopify API limit for your Mechanic account, and therefore does not slow down other tasks. It also does not require any special logic for pagination, since Shopify handles all data collection.

Usage

Creating a bulk operation

Use the Shopify action to execute a bulkOperationRunQuery mutation (see Shopify's tutorial). Mechanic will detect this mutation, and will begin monitoring the bulk operation in progress.

Subscribing to the results

Add a subscription to mechanic/shopify/bulk_operation.

Once Mechanic detects that the bulk operation has been completed, the platform will automatically re-invoked the same task with an event having the topic "mechanic/shopify/bulk_operation", containing the bulk operation's data, when the bulk operation is complete. (As with mechanic/actions/perform, Mechanic will only invoke the current task when the bulk operation completes; no other task will be notified.)

Accessing the results

When processing a mechanic/shopify/bulk_operation event, the task will have access to an environment variable called bulkOperation, containing all attributes of the bulk operation (docs).

The set of objects returned by the bulk operation is made available as bulkOperation.objects, allowing you to scan returned data immediately, using an expression like {% for object in bulkOperation.objects %}.

In most cases, every object that has an ID will appear as a separate object, in the same set of objects. For example, if a product and five variants are returned, there will be six objects returned – the variants are not nested inside of the product object.

The JSON objects returned from bulk operation queries each include a "__parentId" attribute for connected objects, containing the parent object's ID. To make managing task scripts easier, Mechanic allows you to simply call {{ object.__parent }} to look up an object's parent.

{% assign customers = bulkOperation.objects | where: "__typename", "Customer" %}

Example

mechanic/user/trigger
mechanic/shopify/bulk_operation

{% if event.topic == "mechanic/user/trigger" %}
  {% capture bulk_operation_query %}
    query {
      customers {
        edges {
          node {
            __typename
            id
            email
          }
        }
      }
    }
  {% endcapture %}

  {% action "shopify" %}
    mutation {
      bulkOperationRunQuery(
        query: {{ bulk_operation_query | json }}
      ) {
        bulkOperation {
          id
          status
        }
        userErrors {
          field
          message
        }
      }
    }
  {% endaction %}
{% elsif event.topic == "mechanic/shopify/bulk_operation" %}
  {% assign customers = bulkOperation.objects | where: "__typename", "Customer" %}
  {% assign emails = customers | map: "email" %}
  {% log emails: emails %}
{% endif %}

More examples

• Task: Calculate total quantities purchased by SKU

• Task: Sync order timeline comments to the customer note

• Task: Auto-tag orders with their tracking numbers

Use bulk operations when...

• ... your task needs to collect and process a lot of data. Tasks responding to bulk operations operate with a higher memory allowance than other tasks, decreasing the chances of your task being terminated for memory exhaustion.

• ... paginating for data would be too complicated. Pagination in GraphQL can be tricky when using nested resources.

Don't use bulk operations when...

• ... you only need a little bit of data. Use the shopify filter instead.

• ... you're responding to a Shopify event, and the data you need comes along with the event data. Use Liquid objects instead.

In our own internal education, we've found that the following exercises work particularly well. They're all in sequence – the task to create for each subsequent exercise modifies the code you wrote previously.

Assignments

• 1. Auto-tag customers with @gmail.com email addresses, with "gmail"

  • Configure the task's event subscriptions appropriately

  • Support case-insensitivity – recognize "@gmail.com", and "@Gmail.com"

  • Ignore domains with more extensions – don't tag for "@gmail.com.au"

  • Make sure that any existing tags on the customer's account are kept, not lost

  • Use the REST API for this operation

  • Use a static preview action, to show the merchant a preview of what the task will do

• 2. Move to a dynamic preview action, using stub data

• 3. Remove the stub data, and add two event preview definitions: one for a @gmail.com address, and one for another address

• 4. Allow the merchant to configure the domain name to look for, and the tag to apply

  • Help the merchant make sure they enter a real domain name – return an error if the domain doesn't include a "."

  • Support case-insensitivity – if the merchant enters "Gmail.com", and the customer's email address ends with "@GMAIL.COM", they should still be tagged

• 5. Allow the merchant to add any number of domain name and customer tag pairings

• 6. Support responding to customer updates, in which the customer's email address changes

  • Remove any domain name tags that do not apply, and add the tag (if any that does apply

  • Do not remove any tags that contain a domain name tag – if the tag "google" should be removed, do not accidentally remove "google-foo"

  • Make this optional – allow the merchant to choose whether or not Mechanic listens for this

• 7. Move to GraphQL for removing and adding tags

• 8. Allow waiting a configurable number of minutes

  • Account for the customer tags or email address having changed during the waiting period

• 9. Create a backfill mode for processing all existing customers, that the merchant can run manually

  • Use {% for customer in shop.customers %} for this operation

  • Note: this technique is useful for reconciling missing events

• 10. Move to GraphQL for scanning customers

  • See Querying Shopify to learn about looping through results using cursors

• 11. Move to GraphQL bulk operations for scanning customers

The Google Drive action allows you to upload files to your Google Drive.

It supports various file types and can generate files dynamically using file generators, including text files, PDFs, CSVs, and HTML files. Mechanic interacts with Google Drive via the Google Drive API, using OAuth2 for authentication.

Options

Uploads hash structure

The uploads hash supports these properties:

Authentication

This action requires connecting a Google account with the appropriate Drive permissions. To connect an account:

1. Go to the Settings screen

2. Click Authentication

3. Follow the Google account connection flow

Folder Support

Files can be organized in folders by including path information in the filename:

• Use forward slashes to separate folder names (e.g., "reports/2024/monthly/file.pdf")

• Folders will be created automatically if they don't exist

• Can only access folders created by this integration

• Invalid characters not allowed: < > : " / \ | ? *

Path Examples

reports/monthly/report.pdf        # Three levels deep
data/2024/q1/sales.csv           # Four levels deep
archives/backups/files.zip        # Three levels deep

Examples

Simple Text File Upload

{% action "google_drive" %}
  {
    "account": "[email protected]",
    "uploads": {
      "simple.txt": "Hello world!"
    }
  }
{% endaction %}

Multiple Files with Overwrite

{% action "google_drive" %}
  {
    "account": "[email protected]",
    "uploads": {
      "overwrite": true,
      "report.pdf": {
        "pdf": {
          "html": "<h1>Monthly Report</h1><p>This is a PDF generated from HTML</p>"
        }
      },
      "data.csv": "Date,Value\n2024-01-01,100"
    }
  }
{% endaction %}

Files in Folders

{% action "google_drive" %}
  {
    "account": "[email protected]",
    "uploads": {
      "overwrite": true,
      "reports/monthly/sales.pdf": {
        "pdf": {
          "html": "<h1>Monthly Sales Report</h1><p>Data for this month</p>"
        }
      },
      "data/exports/stats.csv": "Date,Value\n2024-01-01,100",
      "archive/backups/data.zip": {
        "zip": {
          "files": {
            "readme.txt": "Backup files",
            "data.csv": "id,value\n1,test"
          }
        }
      }
    }
  }
{% endaction %}

Dynamic File Generation

{% capture report_content %}
  <h1>{{ shop.name }} - Monthly Report</h1>
  <p>Generated on {{ "now" | date: "%Y-%m-%d" }}</p>
  <ul>
    {% for order in shop.orders %}
      <li>{{ order.name }}</li>
    {% endfor %}
  </ul>
{% endcapture %}

{% action "google_drive" %}
  {
    "account": {{ options.google_account | json }},
    "uploads": {
      "overwrite": true,
      "inventory-report.pdf": {
        "pdf": {
          "html": {{ report_content | strip | json }}
        }
      }
    }
  }
{% endaction %}

Action Response

The action returns details about the uploaded files. The response is an object with the following structure:

{
  "uploads": {
    [filepath: string]: {
      "id": string,          // Google Drive file ID
      "name": string,        // File name as stored in Drive
      "mime_type": string,   // MIME type of the uploaded file
      "web_view_link": string, // URL to view the file in Google Drive
      "path": string         // Full folder path where file was created
    }
  }
}

Example response

{
  "uploads": {
    "reports/monthly/report.pdf": {
      "id": "1ABC...xyz",
      "name": "report.pdf",
      "mime_type": "application/pdf",
      "web_view_link": "https://drive.google.com/file/d/1ABC...xyz/view",
      "path": "reports/monthly"
    }
  }
}

The PDF file generator accepts an object containing an HTML string, and uses Pdfcrowd to render it as a PDF document. Pdfcrowd employs the Chromium Embedded Framework for HTML rendering, which uses the same foundation as Google Chrome. This allows Mechanic to generate PDFs with modern CSS and JavaScript features, including chart libraries and web fonts.

Options

{
  "pdf": {
    "html": HTML,
    ...
  }
}

Pdfcrowd options

The PDF generator supports all rendering-related options of the Pdfcrowd API, using version 20.10.

For a complete list of options, see https://pdfcrowd.com/doc/api/html-to-pdf/http/.

Debugging

If it's unclear why something isn't rendering properly, start by testing the HTML being used in a Pdfcrowd playground, at https://pdfcrowd.com/playground/html-to-pdf. If the issue is reproducible in the playground, use the "Help" button along the left-hand sidebar to get the ID of your specific playground, and instructions for contacting Pdfcrowd support with the details of your test.

Example

{% capture html %}
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Liu+Jian+Mao+Cao&display=swap" rel="stylesheet">
<style>p { font-family: 'Liu Jian Mao Cao', cursive; }</style>

<p>Almost before we knew it, we had left the ground.</p>
<div id="tester" style="width:100%;height:40vh;"></div>

<script src="https://cdn.plot.ly/plotly-2.2.0.min.js"></script>
<script>
  // from https://plotly.com/javascript/getting-started/
  TESTER = document.getElementById('tester');
	Plotly.newPlot( TESTER, [{
	x: [1, 2, 3, 4, 5],
	y: [1, 2, 4, 8, 16] }], {
	margin: { t: 0 } } );
</script>
{% endcapture %}

{% action "files" %}
  {
    "file.pdf": {
      "pdf": {
        "html": {{ html | json }},
        "page_width": "7in",
        "page_height": "5in",
        "margin_top": "10mm",
        "margin_right": "10mm",
        "margin_bottom": "10mm",
        "margin_left": "10mm"
      }
    }
  }
{% endaction %}

{
  "action": {
    "type": "files",
    "options": {
      "file.pdf": {
        "pdf": {
          "html": "\n<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\">\n<link rel=\"preconnect\" href=\"https://fonts.gstatic.com\" crossorigin>\n<link href=\"https://fonts.googleapis.com/css2?family=Liu+Jian+Mao+Cao&display=swap\" rel=\"stylesheet\">\n<style>p { font-family: 'Liu Jian Mao Cao', cursive; }</style>\n\n<p>Almost before we knew it, we had left the ground.</p>\n<div id=\"tester\" style=\"width:100%;height:40vh;\"></div>\n\n<script src=\"https://cdn.plot.ly/plotly-2.2.0.min.js\"></script>\n<script>\n  // from https://plotly.com/javascript/getting-started/\n  TESTER = document.getElementById('tester');\n\tPlotly.newPlot( TESTER, [{\n\tx: [1, 2, 3, 4, 5],\n\ty: [1, 2, 4, 8, 16] }], {\n\tmargin: { t: 0 } } );\n</script>\n",
          "page_width": "7in",
          "page_height": "5in",
          "margin_top": "10mm",
          "margin_right": "10mm",
          "margin_bottom": "10mm",
          "margin_left": "10mm"
        }
      }
    }
  }
}

The Flow action sends data to Shopify Flow, arriving as one of four possible Flow triggers.

Options

Resource options

The Flow action accepts at most one resource option, identifying a specific Shopify resource, and resulting in a resource-specific Flow trigger. If no resource option is provided, Mechanic will use the General trigger.

Data options

This action also sends user-defined data, with one option available for each of Flow's supported datatypes. These options are always sent to Flow, even if they're omitted from the action definition; when omitted, their values are set to the documented default.

Usage

For a detailed review of usage, see .

These conversion tutorials will be be based on products, variants, and associated resources, but the methodologies are applicable to other type of REST resources as well.

At a high-level, converting Mechanic tasks from Shopify REST lookups to GraphQL queries involves:

1. Understanding the Shopify GraphQL schema Familiarize yourself with the objects, queries, and mutations.

2. Review how to use GraphQL in Mechanic Start and peruse the to see examples of GraphQL usage in tasks.

3. Identify REST usage within a task Broadly, any usage where one Liquid REST object is used to reference another Liquid REST object with dot notation. This does not include fields on the original REST-like webhook resource (e.g. product.title). For the product and variant resource deprecations specifically, this includes:

   • shop.products

   • shop.variants

   • collection.products

   • inventory_item.variant

   • inventory_level.variant

   • line_item.product

   • line_item.variant

   • product.collections

   • product.images *️

   • product.metafields

   • product.variants *️

   • variant.inventory_item

   • variant.inventory_levels

   • variant.metafields

   • variant.product

4. Field mapping: Identify the objects, fields, and nested structures needed in GraphQL based on the existing REST usage within a task. Build and validate queries using .

5. Update Mechanic task code : Replace the relevant REST calls with Mechanic-flavored Liquid GraphQL query and result objects (see the tutorials following this page for examples).

6. Testing: Trigger the updated task to make sure it returns the expected results and/or takes the expected actions.

Mechanic supports several methods of reading data. The following articles discuss usage, and when each technique might (or might not) be appropriate:

Individual tasks may be optionally configured with their own documentation, formatted with Markdown, providing the user with anything they should know about the task's usage and operation.

Task documentation is shown to the user below the task's options. Documentation is also shown in the confirmation prompt a user sees when they trigger a task that subscribes to either mechanic/user/trigger or mechanic/user/text.

Adding documentation

Task documentation may be managed in Advanced mode.

In Basic mode, documentation is displayed below the task options.

Markdown

Task documentation may be formatted with Markdown, a common syntax for text formatting.

The following table comes from markdownguide.org/cheat-sheet, and is presented with no changes, under the CC BY-SA 4.0 license.

Keyboard Shortcuts

The Markdown editor in Mechanic includes keyboard shortcuts for common formatting operations. These shortcuts can also be accessed through the right click menu in the editor.