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's task library is a compendium of e-commerce automation tasks and documentation, written by the Mechanic community and the Mechanic core team. Hosted on GitHub, everything is open-sourced under the highly permissive MIT license, 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 tasks.mechanic.dev.

The Mechanic community can request new tasks – see Requesting.

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

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

These actions allow your Mechanic tasks to speak to other app and systems :) Use Mechanic to integrate your Shopify store with other apps like Airtable, Google, Slack, and more.

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.

Mechanic is a Shopify development and automation platform.

• for an off-the-shelf solution

• for a task that fits you perfectly

• if you need something else

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

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 generates a new child event, when performed

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

Tasks responding to child events may reference to the parent's event using {{ event.parent }}

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.

A task's code is a 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 , , and .

Report Toaster is a reporting and analytics app, which offers an integration with Mechanic. Use the Report Toaster action to perform operations with their service.

Documentation

Find a complete reference for this action in the Integrations section:

→

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.

Mechanic's 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.

Each task is configured with a specific , 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

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

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.

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.

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 .

Log objects are useful for recording information for later reference. They have no side-effects. Carefully chosen log objects can massively simplify post-hoc debugging, especially (as we've found) when investigating merchant bug reports.

A log object is a plain JSON object, having the following structure:

The log details can be any JSON value.

Log objects are most easily generated using the .

Log objects appear wherever task run results are visible, including the task preview and when viewing an event.

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

The allows developers to submit any request to the Shopify Admin API. By , 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 do not cover the scenario.

Use the to read data. Use the to write or update data.

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

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.

{% for collection in product.collections %}
  {% assign collection_tags = collection.tags | split: ", " %}

  {% if collection_tags contains "my-tag" %}
    {% log collection_with_my_tag: collection.title %}
  {% endif %}
{% endfor %}

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 preview block is often an important step to ensure that Mechanic prompts for the correct scopes for reading and writing Shopify API data.

Mechanic is a development platform – in the hands of a developer, it can be used to accomplish almost anything in Shopify. While our task library 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 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. :)

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"

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 Shopify's recommendation 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

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

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 .

Retried task runs will always use a task's latest configuration, including the task's , , and .

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 , this might be a connection error. For , 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 . 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

In general, Mechanic's run system does not guarantee the execution order for runs that have been created at the same time (see Concurrency). 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.

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 .

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 task code).

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

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 task options 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.

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

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 .

The code above could be utilized directly in a . 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.

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. ;)

and 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

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:

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.

In this tutorial, you'll learn how to publish a Google sheet to the web as a comma-separated values (CSV) file and then fetch that data from Mechanic.

Instructions

1. Create a Google sheet with data.

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

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 Flow action sends data to Shopify Flow, arriving as one of four possible Flow triggers.

Options

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

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.

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 the task library .

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

• Make your changes in your forked repository.

Step-by-step instructions

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

2. Visit the 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 and the supporting documentation. In these next few steps, you'll ensure you can build the , so that you can complete this step when you are ready to submit your contribution.

The Airtable action allows you to create and update tables and records in your Airtable bases.

It provides an authenticated client for HTTP calls to the Airtable API. The various Airtable API methods supported by this integration all share the same top-level structure in the action options.

Options

Supported API Permissions

This integration supports these Airtable API scopes.

• Read/Write Records

• Read/Write Comments

• Read/Write Base Schema

Authentication

This action requires connecting an Airtable account with the appropriate permissions. To connect an account:

1. Go to the Settings screen

2. Click Authentication

3. Follow the Airtable account connection flow from the Airtable tab

Examples

Create a New Table

Add Records to a Table

Action Response

The body of the action response will vary based on which Airtable API method was called. Generally, the response is an object with the following structure (most fields removed for brevity). Running an Airtable action task and reviewing the response is often the best way to see what will be returned in the body.

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

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 .

Debugging

If it's unclear why something isn't rendering properly, start by testing the HTML being used in a Pdfcrowd playground, at . 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

Mechanic-flavored Liquid comes with a complement of Liquid objects, each of which is tied to a resource in the Shopify Admin REST API. 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.

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 and 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!

The Slack action allows Mechanic to post messages to public and private channels in your Slack instance (as the Mechanic app bot or a customer username).

The Slack action provides a wrapper around HTTP calls to the . The various Slack API methods supported by this integration all share the same top-level structure in the action options.

Options

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).

The Base64 file generator accepts a base64-encoded string, and returns a file containing the decoded value.

This generator is useful when producing images, or other binary content that cannot be represented with a JSON string.

Options

This file generator accepts a base64-encoded string. It does not support any other options.

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 .

The Shopify action sends requests to the . Use the to read data; use this action to write or update data.

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).

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 ... %}

During task preview, Mechanic scans the task's subscriptions. For each event topic 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.

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

Examples

Simple Text File Upload

Multiple Files with Overwrite

Files in Folders

Dynamic File Generation

Action Response

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

Example response

The Google action allows you to interact directly with the Google Drive and Sheets APIs, and is a more advanced integration type than the streamlined Google Drive and Google Sheetsactions. The advantage is that it allows use to use any of the features in the Google Drive, Sheets, and Docs REST API. Mechanic interacts with Google using OAuth2 for authentication.

The Google action provides a wrapper around HTTP calls to the Google APIs. The various Google API endpoints supported by this integration all share the same top-level structure in the action options.

Options

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 from the Google tab

Examples

Create Simple Text File

Update Simple Text File

List Drive Files with Name Filter

New Sheet with Data Rows

Action Response

The body of the action response will vary based on which API endpoint is called. Generally, the response is an object with the following structure (most fields removed for brevity). Running a Google action task and reviewing the response is often the best way to see what will be returned in the body.

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.

Subscriptions

Code

At its core, accessing a single resource via either API is effectively the same. Typically this involves passing the ID of the resource to the API and getting back the data for that resource.

{% assign product = shop.products[product_id] %}

In a REST call, every field of that resource will be returned, allowing the usage of simple dot notation to utilize whichever fields are desired without first requesting them.

The equivalent query in GraphQL would need to be augmented to include the desired fields.

This is a basic task to check a product's status, type, and tags, and then output a log entry if that product qualifies.

The preview block is only showing the fields from the REST product webhook that will be used in the task. In reality, there are about 150+ lines of detail from a product webhook which has only a single variant and image. This grows much larger as variants and images are added to the product.

The product id used in the GraphQL query below comes from the REST-like product webhook, which will still exist after the REST product endpoint deprecation.

The preview block simulates the relevant shape of the returned data, which typically matches exactly what was requested in the query. This could vary though based on the task logic following the preview block.

To see a code diff from a Mechanic library task that was recently converted in this manner, click , and review the code variations between the {% if event.topic == "shopify/orders/create" %} blocks.

Tasks may use the shopify Liquid filter to convert GraphQL query strings into simple result objects, by sending the query to the Shopify GraphQL Admin API. The easiest way to build these queries is via the Shopify Admin API GraphiQL explorer, 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.

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 , 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.

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 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.

Supported actions

These are the Mechanic actions that support file generators.

Events, tasks, and actions 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

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

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 action to execute a bulkOperationRunQuery mutation (see ). Mechanic will detect this mutation, and will begin monitoring the bulk operation in progress.

Subscribing to the results

Add a 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 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 called bulkOperation, containing all attributes of the bulk operation ().

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.

Example

Subscriptions

Code

More examples

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 filter instead.

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

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:

Shopify allows apps to inject JavaScript into the online storefront. (This is facilitated by 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.