Tag customers in bulk by email address, with Mechanic.

Mechanic is a development platform for Shopify. :)

Tag customers in bulk by email address

by Isaac Bowen (team@usemechanic.com)

This task prompts you for a list of email addresses and tags, one pair per line, in the format "customer@example.com:tag". The task adds each tag to its related customer. Developers: this task is an example of working in batches with GraphQL – useful when working with bulk data.

Runs when some text is submitted.

15-day free trial – unlimited tasks

Documentation

Enter a list of email addresses and tags, one pair per line, in the format "customer@example.com:tag". The task will add each tag to its related customer, unless (a) the customer already has the tag, (b) the customer could not be found, or (c) a problem was found either with the entered line or with the customer record.

Developer details

Mechanic is designed to benefit everybody: merchants, customers, developers, agencies, Gurus, everybody.

That’s why we make it easy to configure automation without code, why we make it easy to tweak the underlying code once tasks are installed, and why we publish it all here for everyone to learn from.

Events
when some text is submitted (mechanic/user/text)
Script
{% if event.preview %}
  {% assign event = hash %}
  {% assign event["data"] = "customer@example.com:foobar,customer@foo:bar" | replace: ",", newline %}
  {% assign event["preview"] = true %}
{% endif %}

{% assign query_cost = 3 %}
{% assign mutation_cost = 10 %}
{% assign bucket_size = 1000 %}
{% assign buffer_factor = 2 %}

{% assign lines = event.data | strip | split: newline | uniq | sort %}
{% assign lines_and_customers = hash %}

{% assign scan_batch_size = bucket_size | times: 1.0 | divided_by: query_cost | divided_by: buffer_factor | round %}
{% assign scan_batches = lines | in_groups_of: scan_batch_size, fill_with: false %}

{% for scan_batch in scan_batches %}
  {% assign batch_lines = array %}

  {% for line in scan_batch %}
    {% if line == blank %}
      {% continue %}
    {% endif %}

    {% assign parts = line | split: ":" %}
    {% if parts.size != 2 %}
      {% log message: "Found an invalid line.", line: line %}
      {% continue %}
    {% endif %}

    {% unless parts.first contains "@" %}
      {% log message: "Found an invalid email address.", line: line %}
      {% continue %}
    {% endunless %}

    {% assign email = parts[0] | strip %}
    {% assign tag = parts[1] | strip %}

    {% assign batch_lines[batch_lines.size] = email | append: ":" | append: tag %}
  {% endfor %}

  {% if batch_lines == empty %}
    {% continue %}
  {% endif %}

  {% capture query %}
    query {
      {% for line in batch_lines %}
        {% assign email = line | split: ":" | first %}
        customer{{ forloop.index0 }}: customers(first: 1, query: {{ email | json | prepend: "email:" | json }}) {
          edges {
            node {
              id
              email
              tags
            }
          }
        }
      {% endfor %}
    }
  {% endcapture %}

  {% assign result = query | shopify %}

  {% if event.preview %}
    {% capture result_json %}
      {
        "data": {
          {% for line in batch_lines %}
            "customer{{ forloop.index0 }}": {
              "edges": [
                {
                  "node": {
                    "email": {{ line | split: ":" | first | json }},
                    "id": "gid://shopify/Customer/{{ forloop.index0 }}",
                    "tags": []
                  }
                }
              ]
            }
            {% unless forloop.last %},{% endunless %}
          {% endfor %}
        }
      }
    {% endcapture %}

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

  {% for line in batch_lines %}
    {% assign key = "customer" | append: forloop.index0 %}
    {% assign email = line | split: ":" | first %}
    {% assign tag = line | split: ":" | last %}
    {% assign customer = result.data[key].edges.first.node %}

    {% assign customer_email_downcase = customer.email | downcase %}
    {% assign email_downcase = email | downcase %}
    {% if customer_email_downcase != email_downcase %}
      {% log message: "Customer returned by Shopify somehow does not match the email address we searched for. Skipping.", line: line, customer: customer %}
      {% continue %}
    {% endif %}

    {% if customer == nil %}
      {% log message: "This customer could not be found. Skipping.", line: line %}
      {% continue %}
    {% endif %}

    {% if customer.tags contains tag %}
      {% log message: "Customer already has tag. Skipping.", line: line, tag: tag, customer: customer %}
      {% continue %}
    {% endif %}

    {% assign lines_and_customers[line] = customer %}
  {% endfor %}
{% endfor %}

{% assign taggings = array %}

{% for keyval in lines_and_customers %}
  {% assign line = keyval[0] %}
  {% assign tag = line | split: ":" | last %}
  {% assign customer = keyval[1] %}

  {% assign tagging = hash %}
  {% assign tagging["id"] = customer.id %}
  {% assign tagging["tags"] = tag %}

  {% assign taggings[taggings.size] = tagging %}
{% endfor %}

{% if taggings != empty %}
  {% assign tagging_batch_size = bucket_size | times: 1.0 | divided_by: mutation_cost | divided_by: buffer_factor | round %}
  {% assign tagging_batches = taggings | in_groups_of: tagging_batch_size, fill_with: false %}

  {% for tagging_batch in tagging_batches %}
    {% action "shopify" %}
      mutation {
        {% for tagging in tagging_batch %}
          customer{{ forloop.index0 }}: tagsAdd({{ tagging | graphql_arguments }}) {
            userErrors {
              field
              message
            }
            node {
              ... on Customer {
                id
                email
                tags
              }
            }
          }
        {% endfor %}
      }
    {% endaction %}
  {% endfor %}
{% endif %}
Mechanic tasks are written in Liquid, which makes them easy to write and easy to modify. Learn more about our platform.