All pages
Powered by GitBook
1 of 6

Converting tasks from Shopify REST to GraphQL

Important Notice

Shopify is deprecating the Shopify Admin REST API which the Mechanic REST objects depend on. The first round of deprecations involve the product and variant endpoints. Read about the deprecation here and here.

Use the GraphQL going forward. The product and variant objects will cease to work on on Feb 1, 2025 due to the changes being made by Shopify. Shopify will phase out the REST API completely over time, you can read more about this here.

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

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

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

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

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

    • shop.products

    • shop.variants

    • collection.products

    • inventory_item.variant

    • inventory_level.variant

    • line_item.product

    • line_item.variant

    • product.collections

    • product.images *️

    • product.metafields

    • product.variants *️

    • variant.inventory_item

    • variant.inventory_levels

    • variant.metafields

    • variant.product

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

  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.

The product webhook does include an array of images and variants in the product JSON which will still be accessible via dot notation. Note that these are not the same as the previously available Mechanic REST lookups for those resources.

The images and variants data arrays should be used with caution once Shopify releases support for 2 thousand variants per product, in conjunction with the product and variant REST endpoint deprecations. The product webhook will only include full detail for the first 100 variants. It is not yet clear what Shopify will do with images in the product webhook.

Conversion: Single resource lookups

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.

REST - simple product lookup
{% assign product = shop.products[product_id] %}
GraphQL - simple product query
{% 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.

REST - example product logging
{% 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.

Occasionally, the REST and GraphQL APIs do not use the same field names. And in some cases, there are some fields with no counterpart between the APIs. Review the API docs in detail for the resource being queried to make sure the task code is using the correct field names.

GraphQL - example product logging
{% 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.

REST - Basic product tagging task
{% 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.

GraphQL - Basic product tagging task
{% 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

To assist with generating an object query block, you can use the "object_query" snippet in the Mechanic code editor, and it will prompt you to choose the object type to generate a query and preview block for (e.g. product).

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

Conversion: Resource loops to paginated queries

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

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

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

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

Shopify limits most GraphQL resources to 250 records per query, so this will be the most frequent value for the first filter seen in tasks using paginated queries.

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

If a query has the potential to return a very large number of resources (including connected resources) in a shop, then a bulk operation query may be better suited than using paginated GraphQL queries.

GraphQL - paginated products query
{% assign cursor = nil %}
{% assign search_query = nil %}

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

  {% assign result = query | shopify %}

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

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

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

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

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

To assist with generating a paginated query block, you can use the "paginated_query" snippet in the Mechanic code editor, and it will prompt you to choose the object type to paginate over (e.g. products).

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

Conversion: Connections from a resource

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.

REST - Looping through a product's collections
{% 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.

GraphQL - Querying a product's collections with pagination
{% assign cursor = nil %}

{% for n in (1..10) %}
  {% capture query %}
    query {
      product(id: {{ product.admin_graphql_api_id | json }}) {
        collections(
          first: 250
          after: {{ cursor | json }}
        ) {
          pageInfo {
            hasNextPage
            endCursor
          }
          nodes {
            id
            title
            tags
          }
        }
      }
    }
  {% endcapture %}

  {% assign result = query | shopify %}

  {% if event.preview %}
    {% capture result_json %}
      {
        "data": {
          "products": {
            "nodes": [
              {
                "collections": {
                  "nodes": [
                    {
                      "id": "gid://shopify/Collection/1234567890",
                      "title": "Widget collection",
                      "tags": ["my-tag"]
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    {% endcapture %}

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

  {% for collection in result.data.product.collections.nodes %}
    {% if collection.tags contains "my-tag" %}
      {% log collection_with_my_tag: collection.title %}
    {% endif %}
  {% endfor %}

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

To assist with generating a paginated query block, you can use the "paginated_query" snippet in the Mechanic code editor, and it will prompt you to choose the object type to paginate over (e.g. products).

Conversion: Metafield lookups from a resource

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

REST - product metafield value check
{% 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.

GraphQL - product query with metafield and value check
{% 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 %}

Conversion: Resource lookups in task option fields

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

REST - product resource lookup from line item
{%- assign qualifying_product = nil -%}

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

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

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

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

GraphQL - order query with line item products
{%- 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 -%}

Event preview blocks are not evaluated in task option fields. Instead, default values should be assigned to any webhook fields utilized by the query (e.g. product.admin_graphql_api_id). This will keep the task parser happy and allow you to save the task. Be careful though to not assign a default value to a webhook field that can have a null or blank string as a valid value.

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 %}
Email body task option
Email body task option using code flag

The embedded GraphQL query will work without or without using the "code" flag.