If you're creating a new task, and writing a script to go with it, you might see an error like this when you start running it for the first time:

Encountered an error: Received a Shopify error (403): {"errors":"[API] This action requires merchant approval for write_orders scope."}

Mechanic works hard to auto-detect the necessary permissions, and prompt you for them up front. If you see an error message like this one, it means that Mechanic didn't detect everything necessary.

To help Mechanic out, make sure that your task accounts for preview events. These are fake events that Mechanic hands to your task in order to generate the action previews you see on the right-hand side of the task editor. Your task can detect a preview event with an expression like {% if event.preview %}.

Use this feature to make sure that your task always renders a representative set of actions in preview mode, illustrating what your task would do with a live event. Besides being critical for Mechanic, this is super useful for merchants, who should always see an example of what the task is intended to do.


Let's create a task that auto-tags orders coming from email addresses that include @example.com. Why not! :)

{% if order.email contains "@example.com" %}
  {% capture order_tags %}{{ order.tags }}, example.com{% endcapture %}

    "action": {
      "type": "shopify",
      "options": [
          {{ order.id }}
          "tags": {{ order_tags | json }}
{% endif %}

This is what we'd see in the task preview:

This is because, unsurprisingly, the preview event didn't include an @example.com email address. Because of this, no action was generated for the preview, which leaves Mechanic unable to detect the fact that this task requires permission to write orders.

To fix this, we'd modify the first line of the task to look like this:

{% if event.preview or order.email contains "@example.com" %}

This results in the action being rendered both for order #1000 and for preview mode, which allows Mechanic to render an action for preview:

With this information, Mechanic will be able to prompt for the necessary permissions, and the task will have what it needs to run when real order events arrive.

Did this answer your question?