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.

• 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

• 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

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.

Getting Help

Hey there! :) I'm Isaac, the creator of Mechanic.

As of this writing (currently March 30, 2025), AI is not very good at Mechanic. We're seeing a pretty steady stream of folks having issues with AI-generated tasks — issues arising because the AI does not know how Mechanic works. AI code frequently "invents" Mechanic features that do not exist, or fails to invoke necessary Mechanic features.

A time may absolutely come when this gets better. :)

=Isaac

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.

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…

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.

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.

Mechanic is a Shopify development and automation platform.

Can Mechanic help me?

1. Are you working on something Shopify-related?

   • Mechanic is only available for Shopify.

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

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

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

How does Mechanic work?

Tasks, events, and actions

Liquid

Run queues

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.

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

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.

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?

Where can I file a task request?

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

Contributing your work to the task library

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

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

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

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

This tutorial walks you through setting up a custom task in Mechanic, which is called on Contact Form submission on your Shopify frontend, the contents of the form are passed to the task, which emails the contents in CSV format.

Before beginning this tutorial, here's what you'll need:

The situation

We have an online store called Mario's Mushrooms, hosted on Shopify. Business is booming, and our mushrooms are being shipped all over the world. Our CEO, Mario, asks us to connect our default Shopify contact form to our legacy customer relationship management (or CRM) system. We are eager to help! While the CRM doesn't have an HTTP API, it can receive CSV imports via email, which it will then import into its database. This gives us our path forward!

The plan

We are going to make a task in this cool Shopify app called Mechanic. ;) Here's what the task will do:

2. Over on the Mechanic side, the task will receive the form contents, and format them as a CSV file

The Mechanic task

Time to build the task! Out of Mechanic's entire toolkit, here's what we'll use:

Step 1: Create a webhook, and connect it to a new blank task

Step 2: Wire up the shop frontend to send form data to our webhook

We have options here! The only hard requirement is that we use a POST request to send form data to our webhook. This can be done using pure JavaScript, or using a library like jQuery, or even by using plain HTML to set the form tag's action attribute to our webhook URL.

First things first: we're going to make sure of the element ID, for our contact form. This will be important for writing JavaScript that addresses this form. After investigating, we discover that the form ID is "ContactForm". Easy enough!

Next, we're going to write some JavaScript that listens for thesubmit event of this form – functionally, this means that we're going to wire up some code to run when the form is submitted. The goal: to jump in when the form is submitted, send the form data to our webhook (which will then trigger our Mechanic task), and then allow the form to submit as usual. This way, we add Mechanic functionality without disabling the form's existing behavior.

Let's get started on our JavaScript. In your Mechanic task editor, scroll down and find the "JavaScript for Online Storefront" area. This will add this feature to our task, and we'll be given a place to add in our JavaScript, which will be automatically loaded into our shop frontend.

Copy in the JavaScript below, reading the comments for details on what's going on. Remember the "ContactForm" ID? Here's where we get to use it!

// This code will be loaded on all pages of our store. So, we'll need
// to begin by seeing if the current page has a contact form on it,
// to make sure we're not causing errors by trying to modify a form
// that doesn't exist.

// The `contactForm` variable will either be our form (if it's present
// on this page), or will be null (if it isn't).
const contactForm = document.querySelector('#ContactForm');

// Before Mechanic delivers this JavaScript to the storefront, it first
// evaluates it for Liquid. This means that we get to use the `options`
// object. By using {{ options.mechanic_webhook_url__required }}, we can
// make the webhook URL configurable.
const mechanicWebhookUrl = {{ options.mechanic_webhook_url__required | json }};

// We only want to run all of this if there's a contact form on the page.
if (contactForm) {

  // Setting up a flag for later - keep reading!
  let submittedToMechanic = false;

  contactForm.addEventListener(
    'submit',
    (event) => {
      // We're going to prevent the form submit from doing its normal
      // normal. We'll re-submit the form in a second, after we've
      // submitted data to Mechanic.
      event.preventDefault();

      // We'll use fetch to make our POST request:
      // https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
      fetch(
        mechanicWebhookUrl,
        {
          method: 'POST', 
          body: new FormData(contactForm),
        }
      ).then((response) => {
        console.log('Sending data to Mechanic: Success!', response);
      }).catch((error) => {
        console.error('Sending data to Mechanic: Error!', error);
      }).finally(() => {
        // Now that we're done with sending our data to Mechanic,
        // we're going to manually submit the contact form. This won't
        // trigger the "submit" event again; it'll just run the form's
        // usual submit behavior.
        contactForm.submit();
      });
    },
  );
}

When pasting in this code, a new task option will appear, allowing the user (that's us, for now) to configure the webhook URL. Here's where we use the Mechanic-generated webhook URL from earlier.

With all that in place, save the task. We're leaving the task code empty for right now, and that's okay!

Step 4: Receive our form submission on the Mechanic side, convert it to a CSV, and send it as an email attachment

To make sure what data we're working with, let's submit the contact form, and then examine the resulting event data in Mechanic. (It's okay that we hit the captcha prompt; the important part is making sure that we're sending data to Mechanic.)

Heading to the "Events" page of the Mechanic app, we can see our data coming in.

Clicking through to that new event, we can see the event data on the right, reflecting what was in the form at the time of submission. (Depending on the nature of your specific contact form HTML, you might see something slightly different.)

This is perfect! The data we are interested in is inside of an event data property called "contact". This means that, in Liquid, we can access the contact data using {{ event.data.contact }}.

{% assign rows = array %}

{% assign header = array %}
{% assign header[0] = "Name" %}
{% assign header[1] = "Email" %}
{% assign header[2] = "Phone Number" %}
{% assign header[3] = "Message" %}
{% assign rows[rows.size] = header %}

{% assign row = array %}
{% assign row[0] = event.data.contact.name %}
{% assign row[1] = event.data.contact.email %}
{% assign row[2] = event.data.contact.phone %}
{% assign row[3] = event.data.contact.body %}
{% assign rows[rows.size] = row %}

{% assign csv_data = rows | csv %}

{% action "email" %}
  {
    "to": {{ options.recipient_email_address__email_required | json }},
    "subject": {{ options.email_subject__required | json }},
    "body": {{ options.email_body__required_multiline | strip | newline_to_br | json }},
    "attachments": {
       {{ options.csv_attachment_filename__required | replace: ".csv", "" | append: ".csv" | json }}: {{ rows | csv | json }}
     }
   }
{% endaction %}

Here's how we'll configure the task, using the task option fields that automatically appear based on our task code:

Step 5: Testing

With everything assembled, we head back to the contact form, and make a submission. Back in the task editor, we see a new event appear in "Recent activity", with a green checkmark indicating that the task generated and performed an action.

The end!

We did it! We augmented our existing contact form with the ability to send submission data to our new Mechanic task, which relays the data to our CRM system using a CSV email attachment. 🎉

Import the final task

If you'd like to quickly pull in all of the task code and configuration we used here, use this task export:

{"name":"Receive contact form for CRM","options":{"recipient_email_address__email_required":"crm_imports@example.com","email_subject__required":"Contact form submission for CRM: {{ \"now\" | date: \"%Y-%m-%d %H:%M\" }}","email_body__required_multiline":"Hello,\n\nPlease find the attached CSV. Thanks!\n\n-Mechanic, for {{ shop.name }}","csv_attachment_filename__required":"contact-form-for-crm-{{ \"now\" | date: \"%s\" }}","mechanic_webhook_url__required":"https://webhooks.mechanic.dev/00000000-0000-0000-0000-000000000000"},"subscriptions":["user/webhook/form"],"subscriptions_template":null,"script":"{% assign rows = array %}\n\n{% assign header = array %}\n{% assign header[0] = \"Name\" %}\n{% assign header[1] = \"Email\" %}\n{% assign header[2] = \"Phone Number\" %}\n{% assign header[3] = \"Message\" %}\n{% assign rows[rows.size] = header %}\n\n{% assign row = array %}\n{% assign row[0] = event.data.contact.name %}\n{% assign row[1] = event.data.contact.email %}\n{% assign row[2] = event.data.contact.phone %}\n{% assign row[3] = event.data.contact.body %}\n{% assign rows[rows.size] = row %}\n\n{% assign csv_data = rows | csv %}\n\n{% action \"email\" %}\n  {\n    \"to\": {{ options.recipient_email_address__email_required | json }},\n    \"subject\": {{ options.email_subject__required | json }},\n    \"body\": {{ options.email_body__required_multiline | strip | newline_to_br | json }},\n    \"attachments\": {\n       {{ options.csv_attachment_filename__required | replace: \".csv\", \"\" | append: \".csv\" | json }}: {{ rows | csv | json }}\n     }\n   }\n{% endaction %}","docs":null,"halt_action_run_sequence_on_error":false,"liquid_profiling":false,"online_store_javascript":"// This code will be loaded on all pages of our store. So, we'll need\n// to begin by seeing if the current page has a contact form on it,\n// to make sure we're not causing errors by trying to modify a form\n// that doesn't exist.\n\n// The `contactForm` variable will either be our form (if it's present\n// on this page), or will be null (if it isn't).\nconst contactForm = document.querySelector('#ContactForm');\n\n// Before Mechanic delivers this JavaScript to the storefront, it first\n// evaluates it for Liquid. This means that we get to use the `options`\n// object. By using {{ options.mechanic_webhook_url__required }}, we can\n// make the webhook URL configurable.\nconst mechanicWebhookUrl = {{ options.mechanic_webhook_url__required | json }};\n\n// We only want to run all of this if there's a contact form on the page.\nif (contactForm) {\n\n  // Setting up a flag for later - keep reading!\n  let submittedToMechanic = false;\n  \n  contactForm.addEventListener(\n    'submit',\n    (event) => {\n      // We're going to prevent the form submit from doing its normal\n      // normal. We'll re-submit the form in a second, after we've\n      // submitted data to Mechanic.\n      event.preventDefault();\n\n      // We'll use fetch to make our POST request:\n      // https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API\n      fetch(\n        mechanicWebhookUrl,\n        {\n          method: 'POST', \n          body: new FormData(contactForm),\n        }\n      ).then((response) => {\n        console.log('Sending data to Mechanic: Success!', response);\n      }).catch((error) => {\n        console.error('Sending data to Mechanic: Error!', error);\n      }).finally(() => {\n        // Now that we're done with sending our data to Mechanic,\n        // we're going to manually submit the contact form. This won't\n        // trigger the \"submit\" event again; it'll just run the form's\n        // usual submit behavior.\n        contactForm.submit();\n      });\n    },\n  );\n}","order_status_javascript":null,"perform_action_runs_in_sequence":false,"shopify_api_version":"2021-01"}

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:

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.

Lastly, save the task.

3. Test your webhook.

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.

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

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.

You can either create a sheet with the sample data shown below or you can use your own data for this tutorial. Keep in mind that the column headers in the first row will be the exact keys that you need to reference in the task when iterating over the data rows for your own usage.

2. Publish the sheet to the web as a CSV.

From the File / Share menu, choose the Publish to web option.

From the Link tab of the modal dialog that opens, select the sheet you wish to share and the Comma-separated values (.csv) option, and then click the Publish button.

After clicking OK on the confirmation dialog, the modal will update to show you the URL link that you will need to copy into the demonstration task configuration settings. You can safely close this dialog window now.

3. Add and configure the demonstration task.

After adding the task you should update the Gsheet URL option field with the link to your sheet that was generated in the prior step. Update the Alert email recipients with one or more email addresses where you want to be notified in case Mechanic is not able to access the shared sheet (e.g. the share is disabled).

4. Run the task and review the output.

Run the task manually using the Run task button and it will run the first sequence of the task, which will make an HTTP request to GET the sheet data.

To see the results of the data retrieval you need to click on the mechanic/actions/perform child event after it appears.

Next steps

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.

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
• 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
• 10. Move to GraphQL for scanning customers
• 11. Move to GraphQL bulk operations for scanning customers

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!

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:

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

   • variant.inventory_item

   • variant.inventory_levels

   • variant.metafields

   • variant.product

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.

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

{% capture query %}
  query {
    product(id: {{ product_id | json }}) {
      id
      # additional fields as needed
    }
  }  
{% endcapture %}

{% assign result = query | shopify %}

{% assign product = result.data.product %}

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.

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

{% log
  title: product.title,
  status: product.status,
  type: product.product_type,
  description: product.body_html,
  tags: product.tags,
  image: product.image.src
%}

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

{% capture query %}
  query {
    product(id: {{ product_id | json }}) {
      id
      title
      status
      productType
      descriptionHtml
      tags
      featuredImage {
        url
      }
    }
  }  
{% endcapture %}

{% log
  title: product.title,
  status: product.status,
  type: product.productType,
  description: product.descriptionHtml,
  tags: product.tags,
  image: product.featuredImage.url
%}

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.

{% if event.preview %}
  {% capture product_json %}
    {
      "admin_graphql_api_id": "gid://shopify/Product/1234567890",
      "product_type": "Widget",
      "status": "active",
      "tags": "my-tag, some-other-tag"
    }
  {% endcapture %}

  {% assign product = product_json | parse_json %}
{% endif %}

{% assign product_tags = product.tags | split: ", " %}

{% if product.status == "active" and product.product_type == "Widget" %}
  {% if product.tags contains "my-tag" %}
    {% log
      message: "This product qualifies",
      product: product
    %}
  {% endif %}
{% endif %}

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.

{% capture query %}
  query {
    product(id: {{ product.admin_graphql_api_id | json }}) {
      status
      productType
      tags
    }
  }  
{% endcapture %}

{% if event.preview %}
  {% capture result_json %}
    {
      "data": {
        "product": {
          "id": "gid://shopify/Product/1234567890",
          "productType": "Widget",
          "status": "ACTIVE",
          "tags": [
            "my-tag",
            "some-other-tag"
          ]
        }
      }
    }
  {% endcapture %}

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

{% assign product = result.data.product %}

{% if product.status == "ACTIVE" and product.productType == "Widget" %}
  {% if product.tags contains "my-tag" %}
    {% log
      message: "This product qualifies",
      product: product
    %}
  {% endif %}
{% endif %}j

{% assign metafield = product.metafields.custom.my_field %}

{% if metafield.value == "Alpha" %}
  {% log "metafield value matched" %}
{% endif %}

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.

{% capture query %}
  query {
    product(id: {{ product.admin_graphql_api_id | json }}) {
      metafield(key: "custom.my_field") {
        value
      }
    }
  }  
{% endcapture %}

{% assign result = query | shopify %}

{% assign metafield = result.data.product.metafield %}

{% if metafield.value == "Alpha" %}
  {% log "metafield value matched" %}
{% endif %}

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.

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

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.

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

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

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

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.

{% unless event.preview %}
  {% assign customer = customer.reload %}
{% endunless %}

Using Liquid

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

Examples

shopify/orders/create

{% if options.send_email_when_order_cancelled__boolean %}
  shopify/orders/cancelled
{% endif %}

shopify/orders/paid+{{ options.days_to_wait_before_followup__number_required }}.days

shopify/customers/create{% if options.wait_one_hour__boolean %}+1.hour{% endif %}

Example

shopify/customers/create

{% action "email" %}
  {
    "to": {{ options.email_recipient__email_required | json }},
    "subject": {{ options.email_subject__required | json }},
    "body": {{ options.email_body__multiline_required | newline_to_br | json }},
    "from_display_name": {{ shop.name | json }}
  }
{% endaction %}

{"name":"Customer signup alerts","options":{"email_recipient__email_required":"aesha@example.com","email_subject__required":"A new customer has signed up: {{ customer.email }}","email_body__multiline_required":"Hi! View this customer's details online:\n\nhttps://{{ shop.domain }}/admin/customers/{{ customer.id }}\n\n-Mechanic"},"script":"{% action \"email\" %}\n  {\n    \"to\": {{ options.email_recipient__email_required | json }},\n    \"subject\": {{ options.email_subject__required | json }},\n    \"body\": {{ options.email_body__multiline_required | newline_to_br | json }},\n    \"from_display_name\": {{ shop.name | json }}\n  }\n{% endaction %}","subscriptions":["shopify/customers/create"],"online_store_javascript":null,"order_status_javascript":null,"docs":null,"subscriptions_template":"shopify/customers/create","shopify_api_version":"2022-04","liquid_profiling":false,"perform_action_runs_in_sequence":false,"halt_action_run_sequence_on_error":false,"preview_event_definitions":[]}

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:

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

{% unless event.preview %}
  {% assign customer = customer.reload %}
{% endunless %}

Event subject variables

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.

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:

{
  "log": LOG_DETAILS
}

The log details can be any JSON value.

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

Keys

Options are made available in the options variable, which is a hash having key-value pairs for each option key and option value. The option key must only contain ASCII numbers, lowercase letters, and underscores. The option key is reformatted for use as the option name presented to the user – underscores are replaced by spaces, and the entire line is sentence-cased.

Because option keys are registered via static analysis, options must each be referenced using a standard lookup (e.g. options.foobar) at least once.

Order

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

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

Flags

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

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

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

Liquid

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

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

{
  "action": {
    "type": ACTION_TYPE,
    "options": ACTION_OPTIONS,
    "meta": ACTION_META
  }
}

Defining an action

Type

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:

{
  "action": {
    "type": "shopify",
    "options": [
      "post",
      "/admin/customers/1234567890/send_invite.json",
      {}
    ],
    "meta": {
      "invite_reason": "alpha",
      "customer_email": "customer@example.com"
    }
  }
}

{% if event.topic contains "trigger" %}
  {% action %}
    {
      "type": "cache",
      "options": ["set", "foo", "bar"],
      "meta": {
        "mode": "first"
      }
    }
  {% endaction %}
{% elsif action.meta.mode == "first" %}
  {% action %}
    {
      "type": "cache",
      "options": ["set", "foo", "bar"],
      "meta": {
        "mode": "second"
      }
    }
  {% endaction %}
{% elsif action.meta.mode == "second" %}
  {% action "echo", "done" %}
{% endif %}

A task uses its preview to demonstrate what actions the task intends to generate. Among other purposes (see below), this is also how tasks request the Shopify permissions they require.

Mechanic generates a task preview by rendering the task code using a preview event, which resembles a live event that the task may see. The task is then responsible for rendering preview actions in response to the preview event, actions which are visually presented to the user and are analyzed by the platform, but are never actually performed.

Purposes

A preview has three critical purposes:

1. Showing the user that the task will do what they expect it to do

2. Showing the task developer that the task code is functioning as intended

3. Showing the Mechanic platform what permissions the task requires

For users

Core to the design of Mechanic is the idea that we can make it easy to make it easy – in this case, making it easy for developers to show their users what a Mechanic task can be expected to do.

For developers

Developers may think of previews as a sort of test, using preview actions to prove that their task code is functioning as intended. A quality task will exercise all of its code in response to a preview event; doing so gives the developer instant feedback on task results, without actually having to run the task with a live event.

For Mechanic

At the platform level, Mechanic uses previews to determine what permissions a task requires.

Mechanic gets this information from the actions that a task generates during preview, as well as from analysis of the Liquid lookups and GraphQL queries that a task uses during runtime.

Sources

Previews are generated using synthetic, temporary, non-persisted events – at least one for each event topic that the task subscribes to. These events are sourced from one of three places, in order of priority:

2. Or, if the Mechanic account has a recent event with a matching topic on file, the preview will use data from that event;

Detecting preview events

A preview event is identical to a live event in all respects but one: it contains a preview attribute, set to true, identifying it as a preview event.

{% if event.preview %}
  {% log "This is a preview event, generated by Mechanic." %}
{% else %}
  {% log "This is a live event, received by Shopify." %}
{% endif %}

{% if event.preview != true %}
  {% log "This is a live event, received by Shopify." %}
{% else %}
  {% log "This is a preview event, generated by Mechanic." %}
{% endif %}

A preview event's data is taken from the Mechanic account's event history, providing a realistic sample of the data a task can expect to see. (If the account history has no events for a given topic just yet, Mechanic will attempt to use anonymous sample event data of its own.)

Rendering preview actions

A developer can choose between rendering static and dynamic preview actions. Static preview actions are hard-coded, written to appear whenever event.preview is true. Dynamic preview actions are the result of the task code running normally, using event data in preview in the same way that it would use that event data with a live event. Because dynamic preview actions are the result of meaningfully exercising the task's code, they can provide a good indicator of how the task will behave with a live event. By contrast, static preview actions do not provide useful feedback on how a task is coded.

Static preview actions

In the following example, a static preview action demonstrates that the task intends to tag incoming orders with "web". In actuality, the task's intent is to only tag orders that arrive via the Online Store channel; because the task can't be sure whether or not the preview event will contain such an order, a static preview action is used to ensure that a preview event always results in a tagging action.

Branching a task like this has two problems:

1. The actual condition of the task is not exercised during preview. The task will need to be tested with live orders from multiple channels, in order to verify that the task works properly.

2. Duplicating code makes it easier for one copy of the code to fall out of date. By using completely different code for the preview and live actions, it becomes easier for developers to forget to keep the two copies in sync as the task evolves.

{% if event.preview %}
  {% action "shopify" %}
    mutation {
      tagsAdd(id: "gid://shopify/Order/1234567890", tags: "web") {
        userErrors { field, message }
      }
    }
  {% endaction %}
{% elsif order.source_name == "web" %}
  {% action "shopify" %}
    mutation {
      tagsAdd(id: {{ order.admin_graphql_api_id | json }}, tags: "web") {
        userErrors { field, message }
      }
    }
  {% endaction %}
{% endif %}

shopify/orders/create

Dynamic preview actions

A dynamic preview action is the natural result of exercising a task's code as completely as possible, without adding any business logic that responds to event.preview. Put another way, the idea is to make the preview (that appears during task editing) look as similar to a live event as possible.

{% if some_evaluated_condition %}
  {% action "shopify" %}
    mutation {
      tagsAdd(id: {{ order.admin_graphql_api_id | json }}, tags: "web") {
        userErrors { field, message }
      }
    }
  {% endaction %}
{% endif %}

There are two techniques available for "steering" the task towards desired outcomes during preview.

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.

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.

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

{
  "error": ERROR_DETAILS
}

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

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.

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

{% if customer.email contains "gmail.com" %}
  {% log message: "got a gmail user!", email: customer.email %}
{% else %}
  {% log message: "got someone else!", email: customer.email %}
{% endif %}

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

Stubbing Liquid variables

{% if event.preview %}
  {% assign order = hash %}
  {% assign order["source_name"] = "web" %}
  {% assign order["admin_graphql_api_id"] = "gid://shopify/Order/1234567890" %}
{% endif %}

{% if order.source_name == "web" %}
  {% action "shopify" %}
    mutation {
      tagsAdd(id: {{ order.admin_graphql_api_id | json }}, tags: "web") {
        userErrors { field, message }
      }
    }
  {% endaction %}
{% endif %}

{% if event.preview %}
  {% capture order_json %}
    {
      "source_name": "web",
      "admin_graphql_api_id": "gid://shopify/Order/1234567890"
    }
  {% endcapture %}

  {% assign order = order_json | parse_json %}
{% endif %}

{% if order.source_name == "web" %}
  {% action "shopify" %}
    mutation {
      tagsAdd(id: {{ order.admin_graphql_api_id | json }}, tags: "web") {
        userErrors { field, message }
      }
    }
  {% endaction %}
{% endif %}

Stubbing GraphQL data

For this reason, it's important to allow the shopify filter to run normally, and construct stub data afterwards.

{% capture query %}
  query {
    publications(first: 250) {
      edges {
        node {
          id
          name
        }
      }
    }
  }
{% endcapture %}

{% assign result = query | shopify %}

{% if event.preview %}
  {% capture result_json %}
    {
      "data": {
        "publications": {
          "edges": [
            {
              "node": {
                "id": "gid://shopify/Publication/69217648807",
                "name": "Online Store"
              }
            }
          ]
        }
      }
    }
  {% endcapture %}

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

{% log available_publications: result.data.publications %}

{% assign cursor = nil %}
{% assign total_inventory = 0 %}

{% for n in (0..100) %}
  {% capture query %}
    query {
      orders(
        first: 250
        query: "status:open"
        after: {{ cursor | json }}
      ) {
        pageInfo { hasNextPage }
        edges {
          node { name, email }
        }
      }
    }
  {% endcapture %}

  {% assign result = query | shopify %}

  {% if event.preview %}
    {% capture result_json %}
      {
        "data": {
          "orders": {
            "pageInfo": {
              "hasNextPage": false
            },
            "edges": [
              {
                "node": {
                  "name": "#1135",
                  "email": "isaac@example.com"
                }
              }
            ]
          }
        }
      }
    {% endcapture %}

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

  {% for order_edge in result.data.orders.edges %}
    {% assign order_node = order_edge.node %}

    {% if order_node.email == blank %}
      {% continue %}
    {% endif %}

    {% action "email" %}
      {
        "to": {{ order_node.email | json }},
        "subject": {{ "We're still working on " | append: order_node.name | json }},
        "body": "Thanks for your patience!"
      }
    {% endaction %}
  {% endfor %}

  {% if result.data.orders.pageInfo.hasNextPage %}
    {% assign cursor = result.data.orders.edges.last.cursor %}
  {% else %}
    {% break %}
  {% endif %}
{% endfor %}

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

• REST API calls performed to support Liquid lookups

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.

Changing versions

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

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.

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.

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.

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.

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.

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.

{% action "cache" %}
  {
    "incr": {
      "key": "foo",
      "ttl": 600
    }
  }
{% endaction %}

{
  "action": {
    "type": "cache",
    "options": {
      "incr": {
        "key": "foo",
        "ttl": 600
      }
    }
  }
}

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.

{% action "cache", "incr", "foo" %}

{
  "action": {
    "type": "cache",
    "options": [
      "incr",
      "foo"
    ]
  }
}

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

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.

{% action "cache", "setex", "foo", 5, "bar" %}

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

{% action "cache" %}
  {
    "set": {
      "key": "foo",
      "value": 5
    }
  }
{% endaction %}

{% action "cache", "set", "foo", 5 %}

Set a value, explicitly expiring in 1 minute

{% action "cache" %}
  {
    "setex": {
      "key": "foo",
      "ttl": 60,
      "value": 5
    }
  }
{% endaction %}

{% action "cache", "setex", 60, "foo" %}

Clear a value

{% action "cache" %}
  {
    "del": {
      "key": "foo"
    }
  }
{% endaction %}

{% action "cache", "del", "foo" %}

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

Forcing an error

{% action "echo", __error: "Forcing an error!" %}

{
  "action": {
    "type": "echo",
    "options": {
      "__error": "Forcing an error!"
    }
  }
}

Examples

{% action "echo", foo: "bar", baz: "qux" %}

{
  "action": {
    "type": "echo",
    "options": {
      "foo": "bar",
      "baz": "qux"
    }
  }
}

{% action "echo", "foo", "bar", "baz" %}

{
  "action": {
    "type": "echo",
    "options": [
      "foo",
      "bar",
      "baz"
    ]
  }
}

{% action "echo", "foo" %}

{
  "action": {
    "type": "echo",
    "options": "foo"
  }
}

{% action "echo" %}
  {
    "foo": "bar",
    "baz": "qux"
  }
{% endaction %}

{
  "action": {
    "type": "echo",
    "options": {
      "foo": "bar",
      "baz": "qux"
    }
  }
}

Restrictions

Options

Message formatting

HTML and CSS

Mechanic parses each email body for HTML and CSS, allowing authors to use <style> tags without having to think about email client compatibility.

Embedded images

Changing the sender address

This action only supports sending from a single address (regardless of the sender name, as controlled by the from_display_name option).

By default, the sender address is a Mechanic address based on the store's myshopify.com subdomain. For example, the store example.myshopify.com will default to having its mail sent from example@mail.usemechanic.com.

Changing the sender address involves adding it to the store's Mechanic account, and then configuring the email domain name with some DNS records for verification.

Template

To use a specific email template with the Email action, use the template option to specify the name of the desired email template.

Creating email template variables

All options used with the Email action will be made available as Liquid variables for the email template. This means that standard options may be used, like {{ subject }} and {{ body }}, and also custom options: passing in an "order_data" option, containing order data, may allow the email template to show the order name via {{ order_data.name }}.

{% action "email" %}
  {
    "to": "customer@example.com",
    "subject": "Thanks for your order!",
    "template": "order_acknowledgement",
    "order_data": {{ order | json }}
  }
{% endaction %}

This is the first item: {{ order_data.line_items.first.title }}

Remember order {{ order_data.customer.orders.any.first.number }}, your first ever?

Attachments

This action supports attachments given in Mechanic's file generator format. This structure allows the sender to construct a variety of files, including ad-hoc text-based files, PDFs rendered from HTML, files dynamically downloaded from external locations, and ZIP files containing any other files.

Examples

Simple

{% action "email" %}
  {
    "to": "hello@example.com",
    "subject": "Hello world",
    "body": "It's a mighty fine day!",
    "reply_to": {{ shop.customer_email | json }},
    "from_display_name": {{ shop.name | json }}
  }
{% endaction %}

{
  "action": {
    "type": "email",
    "options": {
      "to": "hello@example.com",
      "subject": "Hello world",
      "body": "It's a mighty fine day!",
      "reply_to": "store@example.com",
      "from_display_name": "Example Store"
    }
  }
}

Using HTML

{% capture email_body %}
  <b>Hello!</b>

  It's fantastic to see you!
{% endcapture %}

{% action "email" %}
  {
    "to": "hello@example.com",
    "subject": "Hello world",
    "body": {{ email_body | unindent | strip | newline_to_br | json }}
  }
{% endaction %}