Arigato Automation

Arigato Automation

Twig Code Reference

Twig Code Basics

Overview

This app uses object tokens and the Twig templating engine.
An example of a showing a product title would look like: {{ product.title }}.
Twig filters allow you to modify the token: {{ product.title | upcase }} (makes the title uppercase).
Twig provides a powerful set of tools to do if/else logic, for loops, and deal with arrays.

Twig vs. Liquid

Twig has very similar syntax to Liquid in many cases, but there are some key differences.

  • Twig variable assignment uses {% set var = "value" %} rather than {% assign var = "value" %}
  • Twig filters look like {{ my_var | append("text") }} rather than {{ my_var | append: "text" }}
Twig will also have some different filters than what exist in Liquid, so it is recommended to use this reference page and search for some of the filters you want to use on your variables.

Code Blocks

Twig code is wrapped by {% and %}.

Printing

To print or return a variable you can use:

{{ my_var }}

Functions

Functions can take multiple arguments. The format_address function for example takes an address object and an array of settings:

{{ format_address(address, {company: true, format: 'html'}) }}

Filters

Filters are like functions that apply to a variable like:

{{ my_var | upcase }} (makes the variable uppercase)

Filters can take arguments such as:

{{ my_var | times(10) }} (multiplies the variable by 10)

You can use multiple filters like:

{{ my_var | upcase | truncate(30) }} (makes uppercase and truncates the string)

Twig Tags

if

The if tag allows you to control the flow of your application.

{% if my_num > 20 and my_num <= 100 %}
  {# put your code here #}
{% endif %}

{% if my_string not in my_array %}
  {# put your code here #}
{% endif %}

{% if my_bool == false %}
  {# put your code here #}
{% endif %}

There is a shorthand version of the "if" statement called "ternary". Usage examples:

{{ condition ? returns_if_true : returns_if_false }}
{{ "auto" in "arigato automation" ? "It's automated!" : "Not automated..." }} prints "It's automated!"
{{ my_num <= 0 ? "Less than or equal to zero" : "Greater than zero" }}

for

The for tag allows you to loop over arrays and hashes.

{% for key, value in my_hash %}
  Key: {{ key }}
  Value: {{ value }}
{% endfor %}

You can add an else tag to control what happens when the array is empty.

{% for value in my_array %}
  {# values here #}
{% else %}
  {# my_array is empty #}
{% endfor %}

set

The set tag allows you to create a new variable.

{% set my_string = "new string" %}
{% set my_array = [1, 2, 3, 4] %}

You can also "capture" a chunk of text by using a set and endset tag.

{% set my_long_text %}
  <p>
    This will set multiple lines of text into the "my_long_text" variable.
  </p>
{% endset %}

Twig Variables

Assignment

Twig variables can be created by using:
{% set my_var = "value" %}

Combining Strings

Strings can be combined (concatenated) using the ~ (tilde) character.

{{ my_string ~ " appended text" }}
{% set my_new_string = "prepended " ~ my_var ~ " appeneded" %}

Array vs. Hashes

Arrays are simply a list of one or more values.
Hashes are similar to arrays in that they can contain multiple items.
The primary difference is that hash values have named "keys", whereas arrays use sequential numeric keys.
An example hash:

{% set company_info = {
  name: "Bonify, LLC",
  contact: "support@bonify.io",
  "key with spaces": "some value",
} %}

Hash values can be accessed like:
{{ company_info.contact }} or {{ company_info["key with spaces"] }}

A simple array could look like:

{% set colors = ["red", "blue", "green"] %}

Debugging

If you are unsure how a variable or token is structured you can debug it by using the to_json filter:

{{ my_var | to_json }}

String Filter Reference

matches

Special twig operator that allows for regex.

{% if customer.email matches '/^[a-zA-Z0-9._%+-]+@(?:[a-zA-Z0-9-]+\.)?(google|yahoo)\.[a-zA-Z]{2,}$/i' %}
   true
{% else %}
   false
{% endif %}

debug(item)

Dump the internals of an object similar to PHP's print_r function.

Name Type(s) Description
item mixed The item to inspect.

{{ data | debug }}

contains(needle)

Check if a string contains the needle. This function is "case-sensitive".
Use the icontains filter to ignore case-sensitivity.

Name Type(s) Description
needle string The needle to search for.

{{ "tomato" | contains("tom") }} is TRUE
      
{{ "Apple" | contains("ap") }} is FALSE

icontains(needle)

Check if a string contains the needle. This function is NOT "case-sensitive".
Use the contains filter for case-sensitivity.

Name Type(s) Description
needle string The needle to search for.

{{ "tomato" | icontains("tom") }} is TRUE
      
{{ "apple" | icontains("AP") }} is TRUE

nl2br

The nl2br filter inserts HTML line breaks before all newlines in a string.

{{ "Arigato is amazing.\\nBonify is a bunch of geniuses." | nl2br }}

Prints:

Arigato is amazing.<br />
Bonify is a bunch of geniuses.'

raw

Prevents data from rendering encoded. Particularly useful with Google Sheets.

{{ string_thats_getting_encoded_and_annoying_me | raw }}

upper

Converts a value to uppercase.

{{ 'bonify' | upper }} Prints: "BONIFY"

lower

Converts a value to lowercase.

{{ 'BONIFY' | lower }} Prints: "bonify"

date(formattimezone)

Formats a date. Can format a date, a date modifier string, or a UNIX timestamp.

Name Type(s) Description
format string The date format. Learn more about date formats
timezone string The timezone the date should be displayed in. View valid timezones

{{ "now" | date("m/d/Y") }} becomes 11/08/2024
{{ "-1 month" | date("m/d/Y") }} becomes 10/08/2024
{{ "last year" | date("Y") }} becomes 2023
{{ "now" | date("l, F jS g:iA") }} becomes Friday, November 8th 9:06AM
{{ "yesterday 1AM" | date("l, F jS g:iA") }} becomes Thursday, November 7th 1:00AM
{{ "next thursday 12PM" | date("l, F jS g:iA") }} becomes Thursday, November 14th 12:00PM

Timezone Example:

{{ "today 12pm America/New_York" | date("m/d/Y g:iA", "Australia/Sydney") }} becomes 11/09/2024 4:00AM

date_modify(time)

Modifies a date. Allows you to easily add and subtract time from a date.

Name Type(s) Description
time string The date modifier.

{{ object.created_at | date_modify("+2 days") | date("m/d/Y") }} Adds two days to the created time.
{{ object.created_at | date_modify("+10 minutes") | date("m/d/Y G:i:s") }} Adds ten minutes to the created time.
{{ object.created_at | date_modify("+6 months") | date("m/d/Y") }} Adds six months to the created time.

split(sep)

Splits a string into an array based on the separator.

Name Type(s) Description
sep string The string to separate on.

{% set my_array = "one two three" | split(" ") %} becomes an array of ["one", "two", "three"].

default(value)

Returns a default value if the passed-in variable is empty.

Name Type(s) Description
value string The default value.

{{ my_var | default("my default value") }} Prints "my default value" if my_var is empty.

to_json

Renders a variable as JSON.

{{ object.tags_array | to_json }} becomes a JSON string ['tag 1', 'tag 2'].

from_json(assoc)

Convert a JSON string to an object or array.

Name Type(s) Description
assoc boolean Whether to return an associative array. By default returns a hash object.

{% set my_var = "['red','blue']" | from_json %} (my_var becomes an array).

{% set my_var = '{"name":"John Doe","age":"36"}' | from_json(true) %} (converts the JSON string to an associative array).
{{my_var["name"]}} Outputs "John Doe".

to_handle

Converts a string to "handle" format by removing special characters and replacing spaces with dashes.

{{ "Acme's Product Title!" | to_handle }} becomes "acmes-product-title".

striptags(allowable_tags)

Strip HTML tags from a string. You can set allowable_tags that should not be removed.

Name Type(s) Description
allowable_tags string Tags that should not be stripped.

{{ some_html|striptags }}
{{ some_html|striptags('<br><p>') }}

stripnewlines(item)

Strips new lines from a value.

Name Type(s) Description
item string The string to remove new lines from.

{% set item = "Some words then
More words on another line." %}
{{ item | stripnewlines }}

Prints: "Some words then More words on another line."

strip

Removes all whitespace from the left and right sides of a string.

{% set bad_string = "  bunch of text with space on the ends     " %}
 {{ bad_string  | strip }}
Prints: "bunch of text with space on the ends"

strip_newlines

Removes new lines (line breaks).

{{ "One\nTwo\nThree" | strip_newlines }}} becomes OneTwoThree.

strip_html

Removes HTML tags from a string.

{{ "No <strong>html</strong> tags" | strip_html }} becomes "No html tags".

trim

Trims whitespace on the left and right side of a string.

{{ " has whitespace " | trim }} becomes "has whitespace".

truncate(lengthellipses)

Truncates a string to a specified length.

Name Type(s) Description
length number Max length of the string.
ellipses string An optional ellipses to display when the string is truncated. Default is ...

{{ "My really long string" | truncate(5) }} becomes "My re..."

truncatewords(lengthellipses)

Truncates a paragraph of text to a specified number of words.

Name Type(s) Description
length number Max length of the string.
ellipses string An optional ellipses to display when the string is truncated. Default is ...

{{ "My really long string" | truncatewords(2) }} becomes "My really..."

append(text)

Appends text to a string.

Name Type(s) Description
text string Text to append.

{{ "Arigato" | append(" Automation") }} becomes "Arigato Automation".

prepend(text)

Prepends text before a string.

Name Type(s) Description
text string Text to prepend.

{{ "Automation" | prepend("Arigato ") }} becomes "Arigato Automation".

downcase

Make a string all lowercase.

{{ "Example String" | downcase }} becomes "example string".

upcase

Make a string all uppercase.

{{ "Example String" | upcase }} becomes "EXAMPLE STRING".

capitalize

Capitalizes the first letter in the string.

{{ "example string" | capitalize }} becomes "Example string".

title

Capitalize the first letter of each word.

{{ "example string" | title }} becomes "Example String".

url_encode

The url_encode filter encodes a string as URL segment or an array as query string.

{{ 'path-seg*ment' | url_encode }}                  Prints "path-seg%2Ament"
{{ 'string with spaces' | url_encode }}             Prints "string%20with%20spaces"
{{ {'param': 'value', 'foo': 'bar'} | url_encode }} Prints "param=value&foo=bar"

url_decode

URL decodes a string.

{{ "https%3A%2F%2Fwww.bonify.io" | url_decode }} becomes "https://www.bonify.io".

length

Returns the length of a string.

{{ "example string" | length }} prints "14".

replace(replacements)

Replaces one or more values in a string.

Name Type(s) Description
replacements hash A keyed hash of replacement values.

{{ "one two three" | replace({"one": "1", "two": "2"}) }} prints "1 2 three".

image_url(size|optscrop)

Format a Shopify image with size and crop parameters. Adjusting image size and crop are only available for images hosted on cdn.shopify.com, such as product and variant images.

Name Type(s) Description
size|opts string hash Can be the name of a recognized "size" or a WIDTHxHEIGHT string. Valid sizes include:
  • pico (16x16)
  • icon (32x32)
  • thumb (50x50)
  • small (100x100)
  • compact (160x160)
  • medium (240x240)
  • large (480x480)
  • grande (600x600)
For any given size name you can append the string "_cropped" to crop the image, such as using icon_cropped or compact_cropped.

You can also pass in a keyed hash of settings for width, height, and crop, such as:
{width: 100, height: 100, crop: "center"}
crop string Name of the crop, such as: center, top, right, bottom, left

product.images[0] | image_url("icon") }} Use a predefined size name.
{{ product.images[0] | image_url("icon_cropped") }} Predefined size name and also crop to the size.
{{ product.images[0] | image_url("50x50") }} Specify a max-width and max-height (no cropping).
{{ product.images[0] | image_url("x500") }} Specify a max-height of 500.
{{ product.images[0] | image_url("100x100", "center") }} Specify a size and crop to "center".
{{ product.images[0] | image_url({width:100, height: 100, crop: "center"}) }} Pass a hash of keyed properties.

is_type(type)

Checks if the item is of a given type. See also, the get_type function.

Name Type(s) Description
type string The type to compare with, such as string, integer, double, boolean, hash, array, or NULL. You can also compare against Shopify resource types, such as product, customer, order, draft_order, line_item, etc...

{% if product | is_type("product") %}
    This is a product object.
{% endif %}

{% if "my_string" | is_type("string") %}
    This is a string.
{% endif %}

{% if customer.last_order | is_type("order") %}
    Customer has a valid "Last Order" object.
 {% endif %}

inline_css(html)

Inlines CSS styles in HTML. Learn More
Often used in email templates where inline CSS may be required for some email clients.

Name Type(s) Description
html string The HTML and CSS to merge together.

{% apply inline_css %}
<html>
    <head>
        <style>
            p { color: red; }
        </style>
    </head>
    <body>
        <p>Hello CSS!</p>
    </body>
</html>
{% endapply %}
Gets rendered as inline CSS:

<html>
    <body>
        <p style="color:red;">Hello CSS!</p>
    </body>
</html>
Can be combine with the inky_to_html filter like this:

{%apply inline_css %}
{% apply inky_to_html%}
<style>
  .test { text-align: center;}
  .row { width: 650px; }
  table {width: 100%;}
</style>
<row>
  <columns>put some content here</columns>
  <columns>hello world</columns>
</row>
<row>
  <columns class="test">Some secondary content</columns>
</row>
<row>
  <columns>{{ product.title }}</columns><columns>{{ product.updated_at }}</columns>
</row>
{% endapply %}
{% endapply %}

inky_to_html(inky)

Inky by Foundation is a templating language that converts simple HTML tags into the complex table HTML required for emails.
Learn More | Browse Templates

Name Type(s) Description
inky string The "inky" template to be converted to HTML.

{% apply inky_to_html %}
<container>
  <row>
    <columns>Put content in me!</columns>
  </row>
</container>
{% endapply %}
Gets rendered as HTML:

<html>

<head></head>

<body>
  <table align="center" class="container">
    <tbody>
      <tr>
        <td>
          <table class="row">
            <tbody>
              <tr>
                <th class="small-12 large-12 columns first last">
                  <table>
                    <tbody>
                      <tr>
                        <th>Put content in me!</th>
                        <th class="expander"></th>
                      </tr>
                    </tbody>
                  </table>
                </th>
              </tr>
            </tbody>
          </table>
        </td>
      </tr>
    </tbody>
  </table>
</body>

</html>

format_phone(phone_numbercountry_code)

Formats a phone number in standard E164 format.

Name Type(s) Description
phone_number string The phone number.
country_code string The country code, such as "US", or "GB".

{{ "603 123 9876" | format_phone("US") }} is +16031239876
      
{{ "0778 1419999" | format_phone("GB") }} is +447781419999

Math Filter Reference

at_least(n)

Returns a number at least the value of n

Name Type(s) Description
n number The number to return if the value is less than n.

{{ 10 | at_least(12) }} becomes "12".
{{ 20 | at_least(12) }} becomes "20".

at_most(n)

Returns a number at most the value of n

Name Type(s) Description
n number The number to return if the value is more than n.

{{ 10 | at_most(12) }} becomes "10".
{{ 20 | at_most(12) }} becomes "12".

ceil

Rounds a number up to the nearest integer.

{{ 6.03 | ceil }} becomes "7".

floor

Rounds a number down to the nearest integer.

{{ 6.03 | floor }} becomes "6".

max

Returns the biggest value of a sequence or a set of values.

{{ max(1, 3, 2) }} becomes "3".
{{ max([1, 3, 2]) }} becomes "3".
{{ max({2: "e", 1: "a", 3: "b", 5: "d", 4: "c"}) }} becomes "e".

min

Returns the lowest value of a sequence or a set of values.

{{ min(1, 3, 2) }} becomes "1".
{{ min([1, 3, 2]) }} becomes "1".
{{ min({2: "e", 1: "a", 3: "b", 5: "d", 4: "c"}) }} becomes "a".

number_format(decimalsdec_pointthousands_sep)

Formats a number.

Name Type(s) Description
decimals number The number of decimals to show.
dec_point string The decimal character. Default is . (period)
thousands_sep string The thousands separator. Default is , (comma)

{{ 1234.56 | number_format(0, "", "") }} becomes "1235".
{{ 12 | number_format(2) }} becomes "12.00".
{{ 1234.56 | number_format(2, ".", ",") }} becomes "1,234.56".
{{ 1234.56 | number_format(1, ",", ".") }} becomes "1.234,6".

plus(n)

Adds to a number.

Name Type(s) Description
n number The amount to add.

{{ 10 | plus(10) }} becomes "20".

minus(n)

Subtracts from a number.

Name Type(s) Description
n number The amount to subtract.

{{ 20 | minus(10) }} becomes "10".

times(n)

Multiplies a number.

Name Type(s) Description
n number The amount to multiply by.

{{ 4 | times(3) }} becomes "12".

divided_by(n)

Divides a number.

Name Type(s) Description
n number The amount to divide by.

{{ 10 | divided_by(2) }} becomes "5".

divisible by(n)

Checks if a variable is divisible by a number.

Name Type(s) Description
n number The amount to divide by.

{% if 9 is divisible by(3) %}
    ...
{% endif %}

percent(n)

Multiplies a number by a percentage.

Name Type(s) Description
n number The percent amount.

{{ 10 | percent(20) }} becomes "2".

discount(n)

Discounts an amount by a percentage.

Name Type(s) Description
n number The percent discount.

{{ 10 | discount(20) }} becomes "8".

reverse_discount(n)

Reverses a percentage discount.

Name Type(s) Description
n number The percent discount to reverse.

{{ 8 | reverse_discount(20) }} becomes "10".

Array Filter Reference

contains(needle)

Check if a string contains the needle. This function is "case-sensitive".
Use the icontains filter to ignore case-sensitivity.

Name Type(s) Description
needle string The needle to search for.

{{ "tomato" | contains("tom") }} is TRUE
      
{{ "Apple" | contains("ap") }} is FALSE

map(key)

Maps a keyed array of values to a new array.

Name Type(s) Description
key string The array key to map on.

{% set vehicles = [
  {"make": "honda", "model": "accord"},
  {"make": "ram", "model": "1500"},
] %}
vehicles | map("make") becomes ["honda", "ram"].
vehicles | map("model") becomes ["accord", "1500"].

where(keysearch)

Returns a new array where the array keys match the search value.

Name Type(s) Description
key string The array key to search in.
search string The string to search for.

{% set vehicles = [
  {"make": "honda", "model": "accord"},
  {"make": "honda", "model": "civic"},
  {"make": "ram", "model": "1500"},
  {"make": "mercedes-benz", "model": "c450"}
] %}
{{ vehicles | where("make", "honda") | map("model") | join(", ") }} returns "accord, civic".

join(glue)

Combine items of an array into a string separated by the string.

Name Type(s) Description
glue string The string to put between array items.

{{ ['one','two','three'] | join(" and ") }} becomes "one and two and three".

slice(startlength)

Extracts a slice of an array.

Name Type(s) Description
start number The starting index.
length number The number of items to slice.

{{ ['one','two','three','four'] | slice(1, 2) | join(", ") }} becomes "two, three".

merge

The merge filter merges an array or hash with another array or hash.

Example with arrays:
{% set values = [1, 2] %}
{% set values = values|merge(['apple', 'orange']) %}

values now contains [1, 2, 'apple', 'orange']

Example with hashes:
{% set items = { 'apple': 'fruit', 'orange': 'fruit', 'ram': 'unknown' } %}
{% set items = items|merge({ 'ram': 'car', 'honda': 'car' }) %}

items now contains { 'apple': 'fruit', 'orange': 'fruit', 'ram': 'car', 'honda': 'car' }

sort

Sorts an array. Use the reverse filter to reverse the resulting array.

{{ [8,4,5,1] | sort | join(", ") }} becomes "1, 4, 5, 8".
{{ [8,4,5,1] | sort | reverse | join(", ") }} becomes "8, 5, 4, 1".

compact

Removes empty values from an array.

{{ ['one','','two','three'] | compact | join(", ") }} becomes "one, two, three".

first

Returns the first element of the array.

{{ ['one','two','three'] | first }} prints "one".

last

Returns the last element of the array.

{{ ['one','two','three'] | last }} prints "three".

length

Returns the number of items in an array.

{{ ['one','two','three'] | length }} prints "3".

reverse

Reverses the items in an array.

{{ ['one','two','three'] | reverse | join(", ") }} prints "three, two, one".

keys

Returns the keys of the array.

{% set days = {
  one: "Monday",
  two: "Tuesday",
  three: "Wednesday"
} %}
{{ days | keys | join(", ") }} prints "one, two, three".

range(lowhighstep)

Returns a list containing an arithmetic progression of integers

Name Type(s) Description
low number The first value of the sequence
high number The highest possible value of the sequence.
step number (optional) The increment between elements of the sequence.

{% for i in range(0, 3) %}
  {{ i }},
{% endfor %}

Prints "0, 1, 2, 3"

{% for i in range(0, 6, 2) %}
    {{ i }},
{% endfor %}

Prints "0, 2, 4, 6"

random(valuesmax)

Returns a random value depending on the supplied parameter type. Possible options: a random item from a sequence; a random character from a string; a random integer between 0 and the integer parameter (inclusive). a random integer between the integer parameter (when negative) and 0 (inclusive). a random integer between the first integer and the second integer parameter (inclusive).

Name Type(s) Description
values number (optional) The values
max number (optional) The max value when values is an integer.

{{ random(['apple', 'orange', 'citrus']) }}   Might print "orange"
{{ random('ABC') }}                           Might print "C"
{{ random() }}                                Might print "15386094" (works as the native PHP mt_rand function)
{{ random(5) }}                               Might print "3"
{{ random(50, 100) }}                         Might print "63"

Function Reference

format_address(addressargs)

Formats an address object for various formats.

Name Type(s) Description
address object An address object, such as a customer address or order shipping address.
args hash A keyed hash of arguments (see below).
Name Type(s) Description
company boolean Whether to display the company name.
country boolean Whether to display the country.
phone boolean Whether to display the phone number.
format string Valid formats include html or plain.

base64_encode(data)

Base64 encodes a string.

Name Type(s) Description
data string A string to encode.

base64_decode(data)

Base64 decodes a string.

Name Type(s) Description
data string A base64 encoded string to decode.

base64_image(url)

Base64 encodes a remote image.

Name Type(s) Description
url string External URL to an image.

sha1(data)

Calculate the sha1 hash of a string.

Name Type(s) Description
data string The input string to calculate the hash of.

{{ "bonify" | sha1 }} prints "2d13762cd0ff7f3fb889d78b5ea07930396742ea".

sha256(data)

Calculate the sha256 hash of a string.

Name Type(s) Description
data string The input string to calculate the hash of.

{{ "bonify" | sha256 }} prints "f08f30e7c133c0d762dd0129f038547b5004756bd6d27ee1f5bc8cd4a89425c9".

hash(algorithmdata)

Calculate the hash of a string.

Name Type(s) Description
algorithm string The hash algorithm, such as md5, sha1, or sha256
data string The input string to calculate the hash of.

{{ "bonify" | hash('sha256') }} prints "f08f30e7c133c0d762dd0129f038547b5004756bd6d27ee1f5bc8cd4a89425c9".

order_products_list(orderargs)

Displays a list of products that are part of order line items.

Name Type(s) Description
order object An order object.
args hash A keyed hash of arguments (see below).
Name Type(s) Description
quantity boolean Whether to display quantity ordered.
link boolean Whether to display a link to the product in the store.
format string Valid formats include html, plain, markdown, or slack.

product_link(productargs)

Displays a link to a product in the store.

Name Type(s) Description
product object A product object.
args hash A keyed hash of arguments (see below).
Name Type(s) Description
title string Customize the title of the link. Default is the product title.
format string Valid formats include html, plain, markdown, or slack.

shopify_admin_link(objectargs)

Display an admin link to any resource.

Name Type(s) Description
object object An object, such as a product, customer, order or shop.
args hash A keyed hash of arguments (see below).
Name Type(s) Description
resource string The resource type, such as product.
title string Customize the title of the link. Default title depends on the object type supplied.
format string Valid formats include html, plain, markdown, or slack.

format_money(shopamount)

Display money using the shop's currency format.

Name Type(s) Description
shop object The shop object. Simply pass in shop as it's always available.
amount number The amount of money.

load(resource_typeresource_id)

Get a resource by ID via the Shopify API.

Name Type(s) Description
resource_type string The resource type to load.

The full list of recognizable resource types are:
  • product
  • product_variant
  • order
  • customer
  • draft_order
  • fulfillment
  • fulfillment_event
  • inventory_item
  • inventory_level
  • address
  • checkout
  • discount_allocation
  • discount_application
  • discount_code
  • dispute
  • fulfillment_order
  • fulfillment_service
  • location
  • order_adjustment
  • order_risk
  • product_image
  • refund
  • shop
  • transaction
resource_id number A resource ID.

get_type(item)

Returns the variable type of an item, possible values include:

  • string
  • hash
  • array
  • boolean
  • integer
  • double
  • NULL

If a Shopify resource object is passed in, the name of the resource type will be returned, such as:
  • product
  • customer
  • order
  • draft_order
  • line_item
  • etc...

See also, the is_type filter.

Name Type(s) Description
item mixed The item to get the type of.

{{ get_type("my_string") }} prints "string".
{{ get_type(1234) }} prints "integer".
{{ get_type(product) }} prints "product".
{{ get_type({key:"value"}) }} prints "hash".

Custom Action Reference

Overview

The "Custom Action" in workflows allows you write complex logic to perform actions and even run additional workflows.
While extremely flexible, the Custom Action type has some limitations:

  1. The action has a max runtime limit of 10 seconds.
  2. A maximum of 250 sub-actions can be queued at once in the action when using {% do QUEUE_ACTION() %}
  3. The action can not perform more than 40 Shopify API calls. This limit is imposed by the Shopify API and we are unable to adjust.
  4. Bonify reserves the right to pause or disable any Custom Actions that are performing poorly and could cause system-wide instabilities.
Please reach out to the support team if you want to adjust any limits specified. In some case we may be able to increase them, while in others we may be unable to support your use-case.

Important Methods

Like any other workflow action, the Custom Action allows Twig and tokens.
If you are in a Product workflow, the product object and tokens will be available.
There are three key functions available:

  • RUN_ACTION() Run an action and wait for a result. Returns a result object. Actions that require API calls may take a few seconds to run. Keep that in mind when considering the max runtime limit of the Custom Action, and determine if you should queue the action instead.
  • QUEUE_ACTION() Queue an action to run. Does not return a result.
  • QUEUE_WORKFLOW() Queue a specific workflow to run given a resource object. Does not return a result.
When using RUN_ACTION() you can act upon the returned result by setting a variable:
{% set result = RUN_ACTION(...) %}
When using QUEUE_ACTION() or QUEUE_WORKFLOW() you can run them without setting a result by using the do tag.
{% do QUEUE_ACTION(...) %}
Continue reading below to learn how each function operates.

RUN_ACTION(action_typeargs)

Run an action instantly given a set of additional arguments that are specific to each action type.

Name Type(s) Description
action_type string Name of the action to run.
args hash {key: "value"} pairs of arguments to pass to the action.

There are some universal arguments that can be passed to the RUN_ACTION() function.
These are not specific to any one action type.

Name Type(s) Description
context hash Context is used to pass Twig token information to the action.

Running an action returns a result object which contains important pieces of data:

Name Type(s) Description
result.response array hash The action response data. Will vary by action type.
result.status string Either okay or error.
result.error string An error message if one exists.

{% set result = RUN_ACTION("shopify_api_request", {
  method: "GET",
  path: "orders",
  data: {limit: 5},
  format: "order",
}) %}

{% for order in result.response %}
  {% do QUEUE_ACTION("order_add_tags", {
    resource: order,
    tags: ["a", "b", "c"]
  }) %}
{% endfor %}

An example using context and Twig tokens:

{# Fetch products using an API request and then add tags based on product type and vendor... #}
{% for p in result.response %}
  {% do RUN_ACTION("product_add_tags", {
    resource: p,
    tags: ["{{ my_item.product_type }}:{{ my_item.vendor }}"],
    context: {
      my_item: p
    }
  }) %}
{% endfor %}

QUEUE_ACTION(action_typeargs)

Queue an action to run given a set of additional arguments that are specific to each action type. Queued actions are run asyncronously and do not return a result.

Name Type(s) Description
action_type string Name of the action to run.
args hash {key: "value"} pairs of arguments to pass to the action.

There are some universal arguments that can be passed to the QUEUE_ACTION() function.
These are not specific to any one action type.

Name Type(s) Description
delay string Delay the action until a specific time.
Can be a relative date/time, such as +1 hour or absolute, such as 12/31/2021
context hash Context can used to pass Twig token information to the action.

{# Queue up two actions for a product: product_add_tags and set_metafield #}
{% do QUEUE_ACTION("product_add_tags", {
  resource: product,
  tags: ["a", "b", "c"]
}) %}

{% do QUEUE_ACTION("set_metafield", {
  resource: product,
  namespace: "custom_fields",
  key: "my_text_field",
  value: "my string value"
}) %}

QUEUE_WORKFLOW(workflow_idresource)

Send a given resource to run through a workflow.

The resource being sent to the workflow must be of a type that is accepted by the workflow.
For example, if you have a Workflow that triggers on "Product Updated", a valid Product object must be sent to the workflow.

A "Custom" workflow accepts an HTTP Request object type. You can convert any data or resource to an HTTP Request by using data | as("http_request"). The data will be available in the Custom Workflow in the json token.

A workflow will only run if the resource passes the conditions in the workflow and there are actions to run.

Name Type(s) Description
workflow_id number A workflow ID. The workflow ID can be found in the top-right corner of the screen when editing a workflow.
resource object A resource object, such as a product, customer, order, etc.

{# Get 5 orders that we want to run through a workflow... #}
{% set result = RUN_ACTION("shopify_api_request", {
  method: "GET",
  path: "orders",
  data: {limit: 5},
  format: "order",
}) %}

{# Send each order to an order-based workflow. #}
{% for order in result.response %}
  {% do QUEUE_WORKFLOW(12345, order) %}
{% endfor %}

{# Send orders to a "Custom" workflow which accepts an HTTP Request object type. #}
{% for order in result.response %}
  {% do QUEUE_WORKFLOW(12345, order | as("http_request")) %}
{% endfor %}

Action Types and Arguments

Each action type that can be run will have unique arguments that can be passed to it.

shopify_api_request

Performs a Shopify API request and returns an array of data, or objects, depending on format.

Name Type(s) Description
method string The HTTP method, such as GET, POST, PUT, or DELETE.
path string The API path, such as products, orders/{{ order.id }}.
data hash A hash of data attributes, such as {limit: 10} or {fields: "title,handle,id"}.
format string (optional) The resource type expected in the response data (default is json). If you are fetching Shopify resource types such as products, customers, orders, then set format to product, customer, or order respectively. Doing so loads the data as an Arigato object and provides access to nested data that might otherwise require separate API calls such as metafields. When loaded, the object will work identically to items in the Token Browser.

Running an action returns a result object which contains important pieces of data:

Name Type(s) Description
result.response array hash The action response data. Will vary by action type.
result.status string Either okay or error.
result.error string An error message if one exists.

While the shopify_api_request action type can be used to fetch any type of data from Shopify, there is a select list of recognizable resource types that are handled uniquely in the sytem. These "recognized" resource types can be passed into other actions that support them.

The full list of recognizable resource types are:

  • product
  • product_variant
  • collection
  • order
  • customer
  • draft_order
  • fulfillment
  • fulfillment_event
  • fulfillment_order
  • inventory_item
  • inventory_level
  • address
  • checkout
  • discount_allocation
  • discount_application
  • discount_code
  • dispute
  • fulfillment_service
  • location
  • order_adjustment
  • order_risk
  • product_image
  • refund
  • shop
  • transaction

{# Get 5 orders. #}
{% set result = RUN_ACTION("shopify_api_request", {
  method: "GET",
  path: "orders",
  data: {limit: 5},
  format: "order",
}) %}

{# Update a customer note asynchronously. #}
{% do QUEUE_ACTION("shopify_api_request", {
  method: "PUT",
  path: "customers/{{ customer.id }}",
  data: {customer: {note: "Updating my customer note!"}},
  format: "customer"
}) %}

shopify_graphql_request

Performs a Shopify GraphQL API request.

Name Type(s) Description
query string
variables json
after hash A key/value pair for adding a cursor to the query (see examples).

Running an action returns a result object which contains important pieces of data:

Name Type(s) Description
result.response hash The action response data.
result.status string Either okay or error.

{# Get the first 10 products. List of their titles. Show the query costs. #}
{% set graph_ql = "{
  products(first:10){
    edges{
      node{
        title
        id
        legacyResourceId
      }
    }
  }
}"%}

{% set resp = RUN_ACTION('shopify_graphql_request', {
    query: graph_ql
}) %}

Results:
{% for n in resp.response.data.products.edges %}
    {{ n.node.title }}
{% endfor %}

Requested Query Cost: {{ resp.response.extensions.cost.requestedQueryCost }}
Actual Query Cost: {{ resp.response.extensions.cost.actualQueryCost }}

{# Update the product description through the updateProduct mutation. Debug the response. #}
{% set graph_ql = 'mutation productUpdate($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      title
      description
    }
    userErrors {
      field
      message
    }
  }
}' %}

{% set resp = RUN_ACTION('shopify_graphql_request', {
    query: graph_ql,
    variables: {
        'input': {
            'id': product.admin_graphql_api_id,
            'descriptionHtml': '<span>New description for the product</span>'
        }
    }
}) %}

{{ resp | debug }}

You can paginate through results using the after parameter.
Note that there are strict Shopify API limits. Custom Action also has limits to the number of times you can run an action in a single request.

{% set query %}
{
  products(first:250) {
    edges {
     	node {
        id
        title
      }
    }
    pageInfo{
      hasNextPage
      endCursor
    }
  }
}
{% endset %}

{% set hasNextPage = true %}
{% for i in 0..999 if hasNextPage %}

  {% set result = RUN_ACTION('shopify_graphql_request', {
    query: query,
    after: {products: cursor}
  }) %}

  {% set pageInfo = result.response.data.products.pageInfo %}

  {% for item in result.response.data.products.edges %}
    {{ item.node.id }}: {{ item.node.title }}
  {% endfor %}

  {% set hasNextPage = pageInfo.hasNextPage %}
  {% set cursor = pageInfo.endCursor %}
{% endfor %}

You can paginate through nested results as well:

{% set products_query %}
{
  products(first:5, query:"price:>100") {
    edges {
     	node {
        id
        title
      }
    }
    pageInfo{
      hasNextPage
      endCursor
    }
  }
}
{% endset %}

{% set metafields_query %}
{
  product(id: "PRODUCT_ID") {
    metafields(first:50) {
      edges {
        node {
          namespace
          key
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
{% endset %}

{% set hasNextPage = true %}
{% for i in 0..999 if hasNextPage %}

  {% set result = RUN_ACTION('shopify_graphql_request', {
    query: products_query,
    after: {products: cursor}
  }) %}

  {% set pageInfo = result.response.data.products.pageInfo %}

  {% for item in result.response.data.products.edges %}
    {{ item.node.title }} metafields:

    {% set m_hasNextPage = true %}

    {% for j in 0..999 if m_hasNextPage %}

      {% set m_result = RUN_ACTION('shopify_graphql_request',{
        query: metafields_query | replace({'PRODUCT_ID': item.node.id}),
        after: {metafields: m_cursor}
      }) %}

      {% set m_pageInfo = m_result.response.data.product.metafields.pageInfo %}

      {% for m in m_result.response.data.product.metafields.edges %}
        {{ m.node.namespace }}: {{m.node.key}}
      {% endfor %}

      {% set m_hasNextPage = m_pageInfo.hasNextPage %}
      {% set m_cursor = m_pageInfo.endCursor %}

    {% endfor %}
  {% endfor %}

  {% set hasNextPage = pageInfo.hasNextPage %}
  {% set cursor = pageInfo.endCursor %}
{% endfor %}

http_request

Performs an HTTP request and returns a string. If your request is expected to receive JSON you can use the from_json filter to convert from a JSON string into objects. See example below...

Name Type(s) Description
method string The HTTP method, such as GET, POST, PUT, PATCH, or DELETE.
url string The request URL.
data hash Data to send in the request.
digest hash (optional) Digest authentication credentials. Must include username and password keys.
headers hash {key: "value"} pairs of headers to send with the request.
allow_error_codes array Array of error status codes that can be allowed. If the response status code is in this array, the action will not throw an error.
Name Type(s) Description
status_code number The HTTP status code, such as 200 for OK, or 404 for Not Found.
body string The response body contents. While always returned as a string, JSON can be converted into array/hash by using the from_json filter.
headers hash A keyed hash of response headers.

{% set result = RUN_ACTION("http_request", {
  method: "GET",
  url: "https://api.my-custom-api.org/v1/resource",
  data: {key: "value"},
  allow_error_codes: [404],
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{ shop.database.my_api_key }}"
  }
}) %}

{% if result.response.status_code == 200 %}
  {# Things are good #}
  {% set return_objects = result.response.body | from_json %}
  Got this many objects returned: {{ return_objects | length }}
{% elseif result.response.status_code == 404 %}
  {# Resource not found #}
{% else %}
  {# Something went wrong! #}
{% endif %}

{# Queue an HTTP Request to run asynchrounsly #}
{% do QUEUE_ACTION("http_request", {
  method: "PUT",
  url: "https://api.my-custom-api.org/v1/resource/123",
  data: {update_this: "field"},
  headers: {
    "Content-Type": "application/json",
    "Api-Key": "123123123"
  }
}) %}

product_add_to_collections

Add a product to one or more collections.

Name Type(s) Description
resource object A product object.
collection_ids array An array of collection IDs.

{# This assumes the "product" object is in context. Such as in a Product Created workflow. #}
{% do RUN_ACTION("product_add_to_collections", {
  resource: product,
  collection_ids: [123123123]
}) %}

product_remove_from_collections

Removes a product from one or more collections.

Name Type(s) Description
resource object A product object.
collection_ids array An array of collection IDs.

{# This assumes the "product" object is in context. Such as in a Product Created workflow. #}
{% do QUEUE_ACTION("product_remove_from_collections", {
  resource: product,
  collection_ids: [123123123]
}) %}

product_set_category

Set the standardized product taxonomy category for a product.

Name Type(s) Description
resource object A valid product object.
id string The ID of the category in the format of gid://shopify/TaxonomyCategory/id-value. View List
remove boolean (optional) Mark as TRUE to remove the category from the product.

{# Set a products "Product Category" based on ID. #}
{% do RUN_ACTION("product_set_category", {
  resource: product,
  id: "gid://shopify/TaxonomyCategory/ap-2-3"
}) %}

{# You can display matching category IDs by passing a "name" argument. #}
{% do RUN_ACTION("product_set_category", {
    debug: true,
    resource: product,
    name: "sweatshirts"
}) %}
The debug data will show possible_categories. Use the correct ID in the Custom Action:

[
    {
        "title": "Set the taxonomy category for a product",
        "debug": {
            "debug": true,
            "name": "sweatshirts",
            "is_test": true,
            "possible_categories": [
                {
                    "id": "gid://shopify/TaxonomyCategory/aa-1-1-7-4",
                    "fullName": "Apparel & Accessories > Clothing > Activewear > Activewear Sweatshirts & Hoodies > Sweatshirts"
                },
                {
                    "id": "gid://shopify/TaxonomyCategory/aa-1-13-14",
                    "fullName": "Apparel & Accessories > Clothing > Clothing Tops > Sweatshirts"
                },
                {
                    "id": "gid://shopify/TaxonomyCategory/aa-1-2-9-13",
                    "fullName": "Apparel & Accessories > Clothing > Baby & Toddler Clothing > Baby & Toddler Tops > Sweatshirts"
                }
            ]
        },
    }
]

product_set_custom_product_type

Set a products custom product type.

Name Type(s) Description
resource product The product object.
custom_product_type string The custom_product_type to add to the order.

{% do RUN_ACTION("product_set_custom_product_type", {
  resource: product,
  custom_product_type: "Arigato",
}) %}

product_unpublish

Unpublish a product.

Name Type(s) Description
product object A product object.

{# This assumes the "product" object is in context. Such as in a Product Created workflow. #}
{% do RUN_ACTION("product_unpublish", {
  resource: product,
}) %}

product_update_description

Set the product description. Accepts HTML.

Name Type(s) Description
resource object A product object.
description string The new product description (body_html). May include HTML.

{# This assumes the "product" object is in context. Such as in a Product Created workflow. #}
{% do RUN_ACTION("product_update_description", {
  resource: product,
  description: "My new product description here."
}) %}

Example appending to the description:

{% do RUN_ACTION("product_update_description", {
  resource: product,
  description: "{{ product.body_html }}
 My appended product description here.",
}) %}

product_publish_sales_channels

Publish a product to one or more sales channels.

Name Type(s) Description
resource object A valid product object.
sales_channels array Array of sales channel IDs.

{# View available sales channels when you don't pass in the "sales_channels" arguments #}
{% do RUN_ACTION("product_publish_sales_channels", {
  resource: product
}) %}

{#
  Debug output will contain available sales channels
  [
      {
          "title": "Publish to sales channels",
          "debug": {
              "sales_channels_info": {
                  "gid://shopify/Publication/12341234": "Online Store",
                  "gid://shopify/Publication/98719871": "Point of Sale"
              },
              "user_entered_sales_channels": [],
              "sales_channels": []
          }
      }
  ]
#}

{# Pass a list of IDs to add product to multiple sales channels. #}
{% do RUN_ACTION("product_publish_sales_channels", {
  resource: product,
  sales_channels: ["gid://shopify/Publication/12341234", "gid://shopify/Publication/98719871"]
}) %}

{#
  Debug info will let you know if the entered IDs are "valid" or "invalid".
  {
    "user_entered_sales_channels": {
        "gid://shopify/Publication/12341234": "valid",
        "gid://shopify/Publication/98719871": "valid"
    },
    "sales_channels": [
        "gid://shopify/Publication/12341234",
        "gid://shopify/Publication/98719871"
    ]
  }
#}

product_unpublish_sales_channels

Unpublish a product from one or more sales channels.

Name Type(s) Description
resource object A valid product object.
sales_channels array Array of sales channel IDs.

{# View available sales channels when you don't pass in the "sales_channels" arguments #}
{% do RUN_ACTION("product_unpublish_sales_channels", {
  resource: product
}) %}

{#
  Debug output will contain available sales channels
  [
      {
          "title": "Unpublish from sales channels",
          "debug": {
              "sales_channels_info": {
                  "gid://shopify/Publication/12341234": "Online Store",
                  "gid://shopify/Publication/98719871": "Point of Sale"
              },
              "user_entered_sales_channels": [],
              "sales_channels": []
          }
      }
  ]
#}

{# Pass a list of IDs to remove product from multiple sales channels. #}
{% do RUN_ACTION("product_unpublish_sales_channels", {
  resource: product,
  sales_channels: ["gid://shopify/Publication/12341234", "gid://shopify/Publication/98719871"]
}) %}

{#
  Debug info will let you know if the entered IDs are "valid" or "invalid".
  {
    "user_entered_sales_channels": {
        "gid://shopify/Publication/12341234": "valid",
        "gid://shopify/Publication/98719871": "valid"
    },
    "sales_channels": [
        "gid://shopify/Publication/12341234",
        "gid://shopify/Publication/98719871"
    ]
  }
#}

product_add_tags

Add tags to a given product.

Name Type(s) Description
resource object A valid product object.
tags array An array of tags to add. A comma-delimited string is also allowed.

{# Add tags to a product. #}
{% do RUN_ACTION("product_add_tags", {
  resource: product,
  tags: ["a", "b", "c"]
}) %}

{# Add tags to a product we load specifically by ID. #}
{% set p = load('product', 123123123) %}
{% do QUEUE_ACTION("product_add_tags", {
  resource: p,
  tags: ["d", "e", "f"]
}) %}

product_remove_tags

Remove tags from a given product.

Name Type(s) Description
resource object A valid product object.
tags array An array of tags to remove. A comma-delimited string is also allowed.

{# Remove ALL tags from a product. #}
{% do RUN_ACTION("product_remove_tags", {
  resource: product,
  tags: product.tags
}) %}

product_add_remove_tags

Add & remove tags from a given product.

Name Type(s) Description
resource object A valid product object.
add_tags array An array of tags to add. A comma-delimited string is also allowed.
remove_tags array An array of tags to remove. A comma-delimited string is also allowed.

{% do RUN_ACTION("product_add_remove_tags", {
  resource: product,
  add_tags: ["a", "b"],
  remove_tags: ["c", "d"]
}) %}

set_metafield

Set a metafield value on a resource or at the shop level.

Name Type(s) Description
resource object A valid resource object.
namespace string The metafield namespace.
key string The metafield key.
value number string json The metafield value.
value_type string (optional) Default is string. View list of types.
resource_id number (optional) Only needed if resource is empty.
resource_type string (optional) Only needed if resource is empty.

Arguments for List Metafield Types

value string Comma-delimited list of values to set. To add or remove values use add_values and remove_values.
add_values string Comma-delimited list of values to add to a list metafield type.
allow_duplicates boolean Default is false. Set to true to allow duplicate values to be added to the list.
remove_values string Comma-delimited list of values to remove from a list metafield type.

Some metafield types have additional arguments that are required.

Name Type(s) Description
unit string Required when using a dimension, volume, or weight metafield type.
scale_min number Required when using a rating metafield type.
scale_max number Required when using a rating metafield type.

{# Set a global "shop" metafield. #}
{% do RUN_ACTION("set_metafield", {
  resource: shop,
  namespace: "custom_fields",
  key: "my_string_field",
  value: "Setting a new value here!"
}) %}

{# Set a product metafield based on ID (not a resource object) #}
{% do QUEUE_ACTION("set_metafield", {
  resource_type: "products",
  resource_id: 123123123,
  namespace: "custom_fields",
  key: "my_int_value",
  value: 42,
  value_type: "integer"
}) %}

{# Set a "Volume" type metafield. Notice the additional "unit" argument. #}
{% do RUN_ACTION("set_metafield", {
  resource: product,
  namespace: "my_fields",
  key: "volume",
  value: 100,
  unit: "us_gal",
  value_type: "volume"
}) %}

{# Add and remove values from a list metafield type. #}
{% do RUN_ACTION("set_metafield", {
  resource: product,
  namespace: "my_fields",
  key: "dimension_list",
  value_type: "list.dimension",
  allow_duplicates: true,
  add_values: "1cm, 2in, 3ft",
  remove_values: "10mm, 20mm"
}) %}

{#  Set a metafield on the first variant on a product #}
{% set product = load('product', 12345) %}
{% do RUN_ACTION("set_metafield", {
  resource_type: "variants",
  resource_id: product.variants[0].id,
  namespace: "custom_fields",
  key: "my_key",
  value: "my value"
}) %}

set_database

Set an Arigato Database value on a resource or at the shop level.

Name Type(s) Description
resource object A valid resource object. Can leave empty for setting a global "shop" value.
key string The database key.
value string The database value.
resource_id number (optional) Only needed if resource is empty.
resource_type string (optional) Only needed if resource is empty.

{# Set a global "shop" database value. #}
{% do RUN_ACTION("set_database", {
  key: "list_of_things",
  value: "thing_1, thing_2, thing_3"
}) %}

{# You can then print out the value. #}
{{ shop.database.list_of_things }}

{# Set a database value based on resource_type and resource_id. #}
{% do QUEUE_ACTION("set_database", {
  resource_type: "products",
  resource_id: 123123123,
  key: "some_value",
  value: "Some Value"
}) %}

{# Set a resource's database value. #}
{% do QUEUE_ACTION("set_database", {
  resource: customer,
  key: "some_value",
  value: "Some Value"
}) %}

email

Send an email to a list of email addresses.

Name Type(s) Description
to array string One or more email addresses to send to. You can send a single string, or an array of email addresses. ["email1@example.com", "email2@example.com"]. You can also include names using the format: ["email1@example.com|John Smith", "email2@example.com|Bob Roberts"]
cc array string One or more email addresses to CC.
bcc array string One or more email addresses to BCC.
reply_to string The Reply-To email address.
subject string The email subject line.
body string The email message body.
plain_text boolean Whether the email should be formatted as plain text. Default is false which will send the email as HTML.

{% do QUEUE_ACTION("email", {
  to: shop.email,
  subject: "New order placed!",
  body: "Check out order {{ order.name }}. {{ orders_products_list(order, {format: "html"}) }}",
  plain_text: false,
  context: {order: order}
}) %}

sendgrid

Send an email using Sendgrid to a list of email addresses.

Name Type(s) Description
to array string One or more email addresses to send to. You can send a single string, or an array of email addresses. ["email1@example.com", "email2@example.com"]. You can also include names using the format: ["email1@example.com|John Smith", "email2@example.com|Bob Roberts"]
cc array string One or more email addresses to CC.
bcc array string One or more email addresses to BCC.
reply_to string The Reply-To email address.
subject string The email subject line.
body string The email message body.
plain_text boolean Whether the email should be formatted as plain text. Default is false which will send the email as HTML.

{% do QUEUE_ACTION("sendgrid", {
  to: shop.email,
  subject: "New order placed!",
  body: "Check out order {{ order.name }}. {{ orders_products_list(order, {format: "html"}) }}",
  plain_text: false,
  context: {order: order}
}) %}

google_gmail

Send an send an email using Gmail to a list of email addresses.

Name Type(s) Description
to array string One or more email addresses to send to. You can send a single string, or an array of email addresses. ["email1@example.com", "email2@example.com"]. You can also include names using the format: ["email1@example.com|John Smith", "email2@example.com|Bob Roberts"]
cc array string One or more email addresses to CC.
bcc array string One or more email addresses to BCC.
reply_to string The Reply-To email address.
subject string The email subject line.
body string The email message body.
plain_text boolean Whether the email should be formatted as plain text. Default is false which will send the email as HTML.
from hash A hash of "from" attributes. See below arguments for child attributes.

Valid "From" Attributes

email string This email address must be the one associated with your Gmail account.
name string The "from" name to display.

{% do QUEUE_ACTION("google_gmail", {
  to: shop.email,
  from: {
    name: "John Smith",
    email: "your_address@gmail.com"
  },
  subject: "New order placed!",
  body: "Check out order {{ order.name }}. {{ orders_products_list(order, {format: 'html'}) }}",
  plain_text: false,
  context: {order: order}
}) %}

redirect_create

Create a redirect from an old path to a new path.

Name Type(s) Description
old_path string The old path. Path should start with a forward slash.
new_path string The new path that the old path should redirect to.

{% do RUN_ACTION("redirect_create", {
  old_path: "/my-old-path",
  new_path: "/my-new-path"
}) %}

Example using a product handle.

{% do RUN_ACTION("redirect_create", {
  old_path: "/products/my-old-product-handle-path",
  new_path: "/products/{{ p.handle }}",
  context: {
    p: product
  }
}) %}

product_set_fields

Update one or more fields on a product.

Name Type(s) Description
resource object The product object.
fields object A keyed object of fields that can be updated. See below arguments for child fields.

Valid Fields

title string The product title.
body_html string The product description. Can contain HTML.
handle string The product URL handle.
vendor string The product vendor.
tags array An array of product tags.
template_suffix string The product suffix.
seo_title string The product page SEO title (shown in web searches).
seo_description string The product page SEO description (shown in web searches).
product_type string The custom product type.
category hash A hash containing info about the standardized product taxonomy category. Using an empty value will remove the category.

Valid "category" Attributes

id number The ID of the category. View List
remove boolean (optional) Mark as TRUE to remove the category from the product.

{% do RUN_ACTION("product_set_fields", {
  resource: product,
  fields: {
    title: "New product title",
    handle: "new-product-handle",
    tags: ["a", "b", "c"],
    category: {
      id: "gid://shopify/TaxonomyCategory/ap-2-3",
    },
  }
}) %}

product_variant_set_fields

Update one or more fields on a product variant.

Name Type(s) Description
resource object The product variant object.
fields object A keyed object of fields that can be updated. See below arguments for child fields.

Valid Fields

sku string The variant SKU.
barcode string The variant barcode.
price number The variant price.
compare_at_price number The variant "Compare at" price.
fulfillment_service string The variant fulfillment service.
grams number The variant weight in grams.
weight number The variant weight in weight_units.
weight_unit string The variant weight unit. One of: g, kg, oz, lb.
requires_shipping boolean Whether the variant requires shipping.
inventory_policy string The variant inventory policy. One of: deny, continue.
inventory_management string Name of the variant inventory management system. Default is "shopify".
taxable boolean Whether the variant is taxable.
tax_code string Specifies the Avalara tax code for the product variant. Avalara AvaTax app required.
option1 string Variant option 1 value.
option2 string Variant option 2 value. A second option must first be defined the product otherwise updating option2 will fail.
option3 string Variant option 3 value. A third option must first be defined the product otherwise updating option2 will fail.

{% do RUN_ACTION("product_variant_set_fields", {
  resource: product_variant,
  fields: {
    sku: "NEW-SKU",
    price: 12.99,
    requires_shipping: true,
    option1: "Blue",
    weight: 1.0,
    weight_unit: "lb"
  }
}) %}

customer_set_fields

Update one or more fields on a customer.

Name Type(s) Description
resource object The customer object.
fields hash A keyed hash of fields that can be updated. See below arguments for child fields.

Valid Fields

first_name string The customer first name.
last_name string The customer last name.
email string The customer email address.
phone string The customer phone number.
note string The customer note.
tags array An array of customer tags.
tax_exempt boolean Whether the customer is tax exempt.
accepts_marketing boolean Whether the customer accepts marketing.
verified_email boolean Whether the customer's email has been verified.

{% do RUN_ACTION("customer_set_fields", {
  resource: customer,
  fields: {
    first_name: "David",
    tags: ["a", "b", "c"],
    note: "Awesome customer!",
    accepts_marketing: true
  }
}) %}

order_set_fields

Update one or more fields on an order.

Name Type(s) Description
resource object The order object.
fields hash A keyed hash of fields that can be updated. See below arguments for child fields.

Valid Fields

email string The order email address.
phone string The order phone number.
note string The order note.
tags array An array of order tags.
shipping_address hash An address hash of fields to update (see below).

Address Fields

first_name string The address first name.
last_name string The address last name.
address1 string The first part of the street address.
address2 string The second part of the street address.
city string The address city.
company string The address company name.
phone string The address phone number.
country string The address country.
province string The address province.
zip string The address ZIP code.

{% do RUN_ACTION("order_set_fields", {
  resource: order,
  fields: {
    note: "My order note.",
    tags: ["a", "b", "c"],
    shipping_address: {
      address1: "123 Acme St.",
      country: "US",
      province: "NY",
      city: "New York"
    }
  }
}) %}

draft_order_complete

Completes a draft order, transitions it to an order.

Name Type(s) Description
resource object A valid draft order object.
payment_pending boolean (optional) Mark as TRUE to mark the order as unpaid and payment can be captured later. Mark as FALSE or omit argument to mark the order as paid through the default gateway.

{# Complete a draft order and mark it as paid. #}
{% do RUN_ACTION("draft_order_complete", {
  resource: draft_order,
}) %}

{# Completes a draft order and marks it as payment pending. #}
{% do RUN_ACTION("draft_order_complete", {
  resource: draft_order,
  payment_pending: TRUE
}) %}

draft_order_set_fields

Update one or more fields on a draft order.

Name Type(s) Description
resource object The draft order object.
fields hash A keyed hash of fields that can be updated. See below arguments for child fields.

Valid Fields

email string The draft order email address.
note string The draft order note.
shipping_address hash An address hash of fields to update (see below).
billing_address hash An address hash of fields to update (see below).

Address Fields

first_name string The address first name.
last_name string The address last name.
address1 string The first part of the street address.
address2 string The second part of the street address.
city string The address city.
company string The address company name.
phone string The address phone number.
country string The address country.
province string The address province.
zip string The address ZIP code.

{% do RUN_ACTION("draft_order_set_fields", {
  resource: draft_order,
  fields: {
    note: "My draft order note.",
    shipping_address: {
      address1: "123 Acme St.",
      country: "US",
      province: "NY",
      city: "New York"
    }
  }
}) %}

draft_order_add_tags

Add tags to a given draft order.

Name Type(s) Description
resource object A valid draft order object.
tags array An array of tags to add. A comma-delimited string is also allowed.

{# Add tags to a draft_order. #}
{% do RUN_ACTION("draft_order_add_tags", {
  resource: draft_order,
  tags: ["a", "b", "c"]
}) %}

{# Add tags to a draft_order we load specifically by ID. #}
{% set draft_order = load('draft_order', 123123123) %}
{% do QUEUE_ACTION("draft_order_add_tags", {
  resource: draft_order,
  tags: ["d", "e", "f"]
}) %}

draft_order_remove_tags

Remove tags from a given draft order.

Name Type(s) Description
resource object A valid draft order object.
tags array An array of tags to remove. A comma-delimited string is also allowed.

{# Remove ALL tags from a draft_order. #}
{% do RUN_ACTION("draft_order_remove_tags", {
  resource: draft_order,
  tags: draft_order.tags
}) %}

draft_order_add_remove_tags

Add & remove tags from a given draft order.

Name Type(s) Description
resource object A valid draft order object.
add_tags array An array of tags to add. A comma-delimited string is also allowed.
remove_tags array An array of tags to remove. A comma-delimited string is also allowed.

{% do RUN_ACTION("draft_order_add_remove_tags", {
  resource: draft_order,
  add_tags: ["a", "b"],
  remove_tags: ["c", "d"]
}) %}

inventory_item_set_fields

Update one or more fields on an inventory item.

Name Type(s) Description
resource object The inventory item object.
fields hash A keyed hash of fields that can be updated. See below arguments for child fields.

Valid Fields

cost number The inventory item cost.
tracked boolean Whether the inventory item is tracked.

{% do RUN_ACTION("inventory_item_set_fields", {
  resource: inventory_item,
  fields: {
    cost: 12.99,
    tracked: true
  }
}) %}

delete_resource

Delete any resource such as a product, order, etc.

Name Type(s) Description
resource object A resource object, such a product, customer, order, etc.
resource_type string (optional) A resource type. Acceptable types are: products, variants, customers, orders, draft_orders, blogs, smart_collections, custom_collections, and pages. Only required if resource is not provided.
resource_id number (optional) Shopify's numerical ID of the resource to be deleted. Only required if resource is not provided.

{# This assumes "product" object is in context, such as in a Product Updated workflow. #}
{% do RUN_ACTION("delete_resource", {
  resource: product
}) %}

Example specifying a resource_type and resource_id.

{% do RUN_ACTION("delete_resource", {
  resource_type: "products",
  resource_id: 1234
}) %}

customer_add_note

Add a note to a customer.

Name Type(s) Description
resource object The customer object.
note string The customer note.

{% do RUN_ACTION("customer_add_note", {
  resource: customer,
  note: "My note."
}) %}

customer_add_tags

Add tags to a given customer.

Name Type(s) Description
resource object A valid customer object.
tags array An array of tags to add. A comma-delimited string is also allowed.

{# Add tags to a customer. #}
{% do RUN_ACTION("customer_add_tags", {
  resource: customer,
  tags: ["a", "b", "c"]
}) %}

{# Add tags to a customer we load specifically by ID. #}
{% set customer = load('customer', 123123123) %}
{% do QUEUE_ACTION("customer_add_tags", {
  resource: customer,
  tags: ["d", "e", "f"]
}) %}

customer_remove_tags

Remove tags from a given customer.

Name Type(s) Description
resource object A valid customer object.
tags array An array of tags to remove. A comma-delimited string is also allowed.

{# Remove ALL tags from a customer. #}
{% do RUN_ACTION("customer_remove_tags", {
  resource: customer,
  tags: customer.tags
}) %}

customer_add_remove_tags

Add & remove tags from a given customer.

Name Type(s) Description
resource object A valid customer object.
add_tags array An array of tags to add. A comma-delimited string is also allowed.
remove_tags array An array of tags to remove. A comma-delimited string is also allowed.

{% do RUN_ACTION("customer_add_remove_tags", {
  resource: customer,
  add_tags: ["a", "b"],
  remove_tags: ["c", "d"]
}) %}

customer_update_sms_consent

Update a customer's SMS marketing consent information.

Name Type(s) Description
resource object The customer object.
opt_in_level string The marketing subscription opt-in level that was set when the customer consented to receive marketing information. Acceptable values are: CONFIRMED_OPT_IN, SINGLE_OPT_IN, or UNKNOWN.
marketing_state string The marketing subscription opt-in level that was set when the customer consented to receive marketing information. Acceptable values are: SUBSCRIBED or UNSUBSCRIBED.

{% do RUN_ACTION("customer_update_sms_consent", {
  resource: customer,
  opt_in_level: "CONFIRMED_OPT_IN",
  marketing_state: "SUBSCRIBED",
}) %}

customer_update_email_consent

Update a customer's email marketing consent information.

Name Type(s) Description
resource object The customer object.
opt_in_level string The marketing subscription opt-in level that was set when the customer consented to receive marketing information. Acceptable values are: CONFIRMED_OPT_IN, SINGLE_OPT_IN, or UNKNOWN.
marketing_state string The marketing subscription opt-in level that was set when the customer consented to receive marketing information. Acceptable values are: SUBSCRIBED or UNSUBSCRIBED.

{% do RUN_ACTION("customer_update_email_consent", {
  resource: customer,
  opt_in_level: "CONFIRMED_OPT_IN",
  marketing_state: "SUBSCRIBED",
}) %}

customer_send_invite

Sends an account invite to a customer.

Name Type(s) Description
resource object The customer object.

{% do RUN_ACTION("customer_send_invite", {
  resource: customer,
}) %}

log

Log a message.

Name Type(s) Description
title string A custom title for your log message.
body string The contents you want to log. You can use the debug filter to inspect data structures. Learn more about the debug Twig filter.

{% do RUN_ACTION("log", {
  title: "Product Info",
  body: product | debug
}) %}

ifttt

Send custom events to IFTTT. View Help Documentation.

Name Type(s) Description
event string The name of your custom event.
value1 string The first value to sent to your event.
value2 string The second value to send to your event.
value3 string The third value to send to your event.

{% do RUN_ACTION("ifttt", {
  event: "my_custom_ifttt_event_name",
  value1: "Some valuable data",
  value2: "Some more valuable data",
  value4: "Even more valuable data",
}) %}

order_add_note

Add a note to an order.

Name Type(s) Description
resource object The order object.
note string The note to add to the order.

{% do RUN_ACTION("order_add_note", {
  resource: order,
  note: "This is an important note for this order.",
}) %}

order_add_note_attribute

Add one or more note attributes to this order.

Name Type(s) Description
resource object The order object.
attributes array An array of attribute objects with "name" and "value" keys.

Attribute Fields

name string The attribute name.
value string The attribute value.

{% do RUN_ACTION("order_add_note_attribute", {
  resource: order,
  attributes: [
    { name: "my_attribute_name", value: "A value for this attribute." },
    { name: "my_second_attribute", value: "Another attribute value." }
  ]
}) %}

order_add_line_item

Adds a line item to an existing order.

Name Type(s) Description
resource object The order object.
variant_id string Enter the ID of the variant to add to the order. The ID of a variant can be found at the end of the URL of a variant when viewed in the Shopify interface.
quantity integer Enter the quantity to add to the order.
allow_duplicates boolean If true, the workflow adds the variant quantity to the order, even if the variant is already part of the order.
inventory_location string The ID of the inventory location to use when adding the variant to the order. If not specified, the workflow uses the default inventory location.

{% do RUN_ACTION("order_add_line_item", {
    resource: order,
    variant_id: "47406627881249",
    quantity: 1,
    allow_duplicates: false,
    inventory_location: "123456789"
}) %}

order_add_tags

Add tags to a given order.

Name Type(s) Description
resource object A valid order object.
tags array An array of tags to add. A comma-delimited string is also allowed.

{# Add tags to a order. #}
{% do RUN_ACTION("order_add_tags", {
  resource: order,
  tags: ["a", "b", "c"]
}) %}

{# Add tags to a order we load specifically by ID. #}
{% set order = load('order', 123123123) %}
{% do QUEUE_ACTION("order_add_tags", {
  resource: order,
  tags: ["d", "e", "f"]
}) %}

order_remove_tags

Remove tags from a given order.

Name Type(s) Description
resource object A valid order object.
tags array An array of tags to remove. A comma-delimited string is also allowed.

{# Remove ALL tags from a order. #}
{% do RUN_ACTION("order_remove_tags", {
  resource: order,
  tags: order.tags
}) %}

order_add_remove_tags

Add & remove tags from a given order.

Name Type(s) Description
resource object A valid order object.
add_tags array An array of tags to add. A comma-delimited string is also allowed.
remove_tags array An array of tags to remove. A comma-delimited string is also allowed.

{% do RUN_ACTION("order_add_remove_tags", {
  resource: order,
  add_tags: ["a", "b"],
  remove_tags: ["c", "d"]
}) %}

order_cancel

Cancel an order.

Name Type(s) Description
resource object The order object.
reason string Reason for cancelling the order. Acceptable values are: customer (Customer changed or cancelled order), inventory (Items unavailable), fraud(Fraudulent order), declined (Payment declined), other (Other).
restock boolean Set to true to add product quantities back to your store false to do nothing.
void boolean Set to true to void any pending credit card authorizations on the order. If payment has already been captured or collected, this setting will not refund any money already collected. Use the Refund Order action to refund any money already collected. Set to false to do nothing.
notify_customer boolean Set to true to send a notification to the customer or false to do nothing.

{% do RUN_ACTION("order_cancel", {
  resource: order,
  reason: "other",
  restock: true,
  void: true,
  notify_customer: false,
}) %}

order_capture_payment

Capture the entire authorized payment amount for the order.

Name Type(s) Description
resource object The order object.

{% do RUN_ACTION("order_capture_payment", {
  resource: order,
}) %}

order_close

Archive an order

Name Type(s) Description
resource object The order object.

{% do RUN_ACTION("order_close", {
  resource: order,
}) %}

order_open

Unarchive an order

Name Type(s) Description
resource object The order object.

{% do RUN_ACTION("order_open", {
  resource: order,
}) %}

order_refund

Refund an order.

Name Type(s) Description
resource object The order object.
currency string 3-letter currency code. Use {{ shop.currency }} for the Shop's currency code.
note string Optional refund note.
restock_type string How to handle restocking inventory. Acceptable values are: no_restock(Do not restock), cancel (Cancel: items not yet delivered) return (Return: items already delivered).
refund_shipping boolean Set to true to refund the clost of shipping. Set to false to do nothing.
notify_customer boolean Set to true to notify the customer. Set to false to do nothing.

{% do RUN_ACTION("order_refund", {
  resource: order,
  currency: shop.currency,
  note: "We messed this up.",
  restock_type: "no_restock",
  refund_shipping: false,
  notify_customer: false,
}) %}

order_void_transactions

Voids any pending credit card authorizations on the order. If payment has already been captured or collected, this action will not refund any money already collected. Use the Refund Order action to refund any money already collected.

Name Type(s) Description
resource object The order object.

{% do RUN_ACTION("order_void_transactions", {
  resource: order,
}) %}

order_fulfill

Fulfill all items in an order. If you want to fulfill a specific line item in the order you can use line_item_fulfill on a specific line item.

Name Type(s) Description
resource object The order object.
message string A message that's associated with the fulfillment request. This message is only available if the associated fulfillment order is assigned to a third-party fulfillment service that has opted in to managing fulfillment orders.
notify_customer boolean Whether to notify the customer of the fulfillment.
tracking_info hash A keyed hash of tracking-specific fields.

Tracking Info Fields

number string The tracking number for the fulfillment.
url string The URL to the tracking page for the fulfillment.
company string The machine name of the shipping company that is handling the fulfillment, such as usps or ups_shipping.

{% do RUN_ACTION("order_fulfill", {
  resource: order,
  message: "Leave at the front gate.",
  notify_customer: false,
  tracking_info: {
    "number": "1234567890",
    "url": "https://www.example.com",
    "company": "usps"
  }
}) %}

order_create_risk

Create a new order risk.

Name Type(s) Description
resource object The order object.
recommendation string A recommendation of either cancel, investigate, or accept.
message string The message that's displayed in the Fraud Analysis section for the order.

{% do RUN_ACTION("order_create_risk", {
  resource: order,
  recommendation: "investigate",
  message: "Arigato Automation detected an issue with this order.",
}) %}

line_item_fulfill

Fulfill an order's line item. If you want to fulfill all line items in an order you can use order_fulfill on the order.

Name Type(s) Description
resource object The line item object.
message string A message that's associated with the fulfillment request. This message is only available if the associated fulfillment order is assigned to a third-party fulfillment service that has opted in to managing fulfillment orders.
notify_customer boolean Whether to notify the customer of the fulfillment.
tracking_info hash A keyed hash of tracking-specific fields.

Tracking Info Fields

number string The tracking number for the fulfillment.
url string The URL to the tracking page for the fulfillment.
company string The machine name of the shipping company that is handling the fulfillment, such as usps or ups_shipping.

Example given a single order line item.

{% do RUN_ACTION("line_item_fulfill", {
  resource: line_item,
  message: "Leave at the front gate.",
  notify_customer: false,
  tracking_info: {
    "number": "1234567890",
    "url": "https://www.example.com",
    "company": "usps"
  }
}) %}

Example fulfilling a specific line item in an order.

{% for line_item in order.line_items %}
  {% if line_item.title | contains("Digital") %}
    {% do RUN_ACTION("line_item_fulfill", {
      resource: line_item,
    }) %}
  {% endif %}
{% endfor %}

fulfillment_cancel

Cancel a fulfillment.

Name Type(s) Description
resource object The fulfillment object.

{% do RUN_ACTION("fulfillment_cancel", {
  resource: fulfillment,
}) %}

fulfillment_update_tracking

Update the tracking info for a fulfillment, including the tracking number, tracking URL, and shipping company.

Name Type(s) Description
resource object The fulfillment object.
notify_customer boolean Whether to notify the customer of the tracking update.
tracking_info hash A keyed hash of tracking-specific fields.

Tracking Info Fields

number string The tracking number for the fulfillment.
url string The URL to the tracking page for the fulfillment.
company string The machine name of the shipping company that is handling the fulfillment, such as usps or ups_shipping.

{% do RUN_ACTION("fulfillment_update_tracking", {
  resource: fulfillment,
  notify_customer: false,
  tracking_info: {
    "number": "1234567890",
    "url": "https://www.example.com",
    "company": "usps"
  }
}) %}

fulfillment_order_fulfill

Fulfill all items in a fulfillment order.

Name Type(s) Description
resource object The fulfillment order object.
message string A message that's associated with the fulfillment request. This message is only available if the associated fulfillment order is assigned to a third-party fulfillment service that has opted in to managing fulfillment orders.
notify_customer boolean Whether to notify the customer of the fulfillment.
tracking_info hash A keyed hash of tracking-specific fields.

Tracking Info Fields

number string The tracking number for the fulfillment.
url string The URL to the tracking page for the fulfillment.
company string The machine name of the shipping company that is handling the fulfillment, such as usps or ups_shipping.

{% do RUN_ACTION("fulfillment_order_fulfill", {
  resource: fulfillment_order,
  message: "Leave at the front gate.",
  notify_customer: false,
  tracking_info: {
    "number": "1234567890",
    "url": "https://www.example.com",
    "company": "usps"
  }
}) %}

fulfillment_order_move

Move a fulfillment order from its current location to a new location. Please be advised, you are only able to move a fulfillment order from one merchant managed location to another merchant managed location that stocks the line items on the fulfillment order.

Name Type(s) Description
debug boolean When debug is true, the action will display a list of location IDs and corresponding location information.
resource object The fulfillment order object.
location_id string The ID of the location the fulfillment order is being moved to.

{# Use the "debug" argument to display location options. Note, only valid options for the test object are returned. #}

{% do RUN_ACTION("fulfillment_order_move", {
  debug: true,
  resource: fulfillment_order
}) %}
{# The resulting debug information will be shown: #}
{
    "title": "Move a fulfillment order.",
    "location_options": {
        "61592567991": "Location Name 1 - City, State/Providence",
        "62002036919": "Location Name 2 - City, State/Providence",
        "62002069687": "Location Name 3 - City, State/Providence",
    }
}

Enter the location_id you wish to move the fulfillment order to.

{# Move a fulfillment order. #}
{% do RUN_ACTION("fulfillment_order_move", {
      debug: true,
      resource: fulfillment_order,
      location_id: "61592567991"
}) %}

{# The resulting confirmation debug information will be shown: #}
{
    "title": "Move a fulfillment order.",
    "location_id": "Location Name 1 - City, State/Providence [61592567991]"
}

fulfillment_order_hold

Hold a fulfillment order.

Name Type(s) Description
resource object The fulfillment order object.
reason string A reason for the fulfillment hold. Acceptable values are: awaiting_payment, high_risk_of_fraud, incorrect_address, inventory_out_of_stock, or other.
reason_notes string Additional information about the fulfillment hold reason.
notify_merchant boolean If set to true, the merchant will be notified on the Shopify mobile app if they use it to manage their store.

{# Hold a fulfillment order. #}
{% do RUN_ACTION("fulfillment_order_hold", {
      resource: fulfillment_order,
      reason: "awaiting_payment",
      reason_notes: "The customer has not paid for their order."
}) %}

fulfillment_order_release_hold

Release the fulfillment hold on a fulfillment order and changes the status of the fulfillment order to OPEN or SCHEDULED.

Name Type(s) Description
resource object A fulfillment order object.

{% do RUN_ACTION("fulfillment_order_release_hold", {
  resource: fulfillment_order,
}) %}

fulfillment_order_line_item_fulfill

Fulfill one or more items in a specific fulfillment order line item.

Name Type(s) Description
resource object The fulfillment order line item object.
quantity number Number of items to fulfill. Leave blank to fulfill ALL items in the line item.
message string A message that's associated with the fulfillment request. This message is only available if the associated fulfillment order is assigned to a third-party fulfillment service that has opted in to managing fulfillment orders.
notify_customer boolean Whether to notify the customer of the fulfillment.
tracking_info hash A keyed hash of tracking-specific fields.

Tracking Info Fields

number string The tracking number for the fulfillment.
url string The URL to the tracking page for the fulfillment.
company string The machine name of the shipping company that is handling the fulfillment, such as usps or ups_shipping.

{% do RUN_ACTION("fulfillment_order_line_item_fulfill", {
  resource: line_item,
  quantity: 1,
  message: "Leave at the front gate.",
  notify_customer: false,
  tracking_info: {
    "number": "1234567890",
    "url": "https://www.example.com",
    "company": "usps"
  }
}) %}

product_image_set_alt

Set an alt tag for the product image.

Name Type(s) Description
resource object An image object, such as from product.images[0], or product.variants[0].image.
alt string The text of the alt tag

{% set product = load('product', 123456789) %}

{% set image = product.images[0] %}

{% do RUN_ACTION("product_image_set_alt", {
  resource: image,
  alt: "New alt tag",
}) %}

{% set image = product.variants[0].image %}

{% do RUN_ACTION("product_image_set_alt", {
  resource: image,
  alt: "edited variant version",
}) %}

product_publish

Publish a product.

Name Type(s) Description
resource object The product object.

{% do RUN_ACTION("product_publish", {
  resource: product,
}) %}

product_variant_set_price

Set a product variant price by entering a dollar amount.

Name Type(s) Description
resource object The product variant object.
price number The dollar amount to set as the variant price.

{% do RUN_ACTION("product_variant_set_price", {
  resource: product_variant,
  price: 25.00
}) %}

product_variant_discount

Increase or decrease a product variant price by applying a percent or dollar amount discount.

Name Type(s) Description
resource object The product variant object.
discount number The amount of the discount.
discount_type string The type of the discount. Acceptable values are: percent (apply a discount by a percent) or dollars (apply a discount in dollars or whatever the shop's currency is.)
reverse boolean Undo this discount. This will increase the price by undoing the entered discount.
reverse_safe boolean Only increase the price if it was already decreased. This ensures the discount will only be undone if it was already applied.
once boolean Only apply this discount once per variant. This ensures the discount will be only be executed one time for a given variant. Leave this unchecked if a variant can be discounted multiple times.

{% do RUN_ACTION("product_variant_discount", {
  resource: product_variant,
  discount: 10,
  discount_type: "percent",
  reverse: false,
  reverse_safe: false,
  once: true,
}) %}

collection_publish

Publish a collection.

Name Type(s) Description
resource object The collection object.

{% do RUN_ACTION("collection_publish", {
  resource: collection,
}) %}

collection_unpublish

Unpublish a collection.

Name Type(s) Description
resource object The collection object.

{% do RUN_ACTION("collection_unpublish", {
  resource: collection,
}) %}

collection_update_image

Update a collections image and alt text.

Name Type(s) Description
resource object The collection object.
image string Fully qualified path to new image. Leave blank to only update the alt text.
alt string The alt text for the collection image.

{% do RUN_ACTION("collection_update_image", {
  resource: collection,
  image: "http://cdn.shopify.com/path/to/the/image.jpeg",
  alt: "The alt text for the new image"
}) %}

collection_set_fields

Set title, handle, and/or description of a collection.

Name Type(s) Description
resource object The collection object.
title string The collection title.
body_html string The collection description. Can contain HTML.
handle string The collection URL handle.

{% do RUN_ACTION("collection_set_fields", {
  resource: collection,
  fields: {
    title: "New collection title",
    body_html: "New collection description.",
    handle: "new-collection-handle",
  }
}) %}

collection_publish_sales_channels

Publish a collection to one or more sales channels.

Name Type(s) Description
resource object A valid collection object.
sales_channels array Array of sales channel IDs.

{# View available sales channels when you don't pass in the "sales_channels" arguments #}
{% do RUN_ACTION("collection_publish_sales_channels", {
  resource: collection
}) %}

{#
  Debug output will contain available sales channels
  [
      {
          "title": "Publish to sales channels",
          "debug": {
              "sales_channels_info": {
                  "gid://shopify/Publication/12341234": "Online Store",
                  "gid://shopify/Publication/98719871": "Point of Sale"
              },
              "user_entered_sales_channels": [],
              "sales_channels": []
          }
      }
  ]
#}

{# Pass a list of IDs to add collection to multiple sales channels. #}
{% do RUN_ACTION("collection_publish_sales_channels", {
  resource: collection,
  sales_channels: ["gid://shopify/Publication/12341234", "gid://shopify/Publication/98719871"]
}) %}

{#
  Debug info will let you know if the entered IDs are "valid" or "invalid".
  {
    "user_entered_sales_channels": {
        "gid://shopify/Publication/12341234": "valid",
        "gid://shopify/Publication/98719871": "valid"
    },
    "sales_channels": [
        "gid://shopify/Publication/12341234",
        "gid://shopify/Publication/98719871"
    ]
  }
#}

collection_unpublish_sales_channels

Unpublish a collection from one or more sales channels.

Name Type(s) Description
resource object A valid collection object.
sales_channels array Array of sales channel IDs.

{# View available sales channels when you don't pass in the "sales_channels" arguments #}
{% do RUN_ACTION("collection_unpublish_sales_channels", {
  resource: collection
}) %}

{#
  Debug output will contain available sales channels
  [
      {
          "title": "Unpublish from sales channels",
          "debug": {
              "sales_channels_info": {
                  "gid://shopify/Publication/12341234": "Online Store",
                  "gid://shopify/Publication/98719871": "Point of Sale"
              },
              "user_entered_sales_channels": [],
              "sales_channels": []
          }
      }
  ]
#}

{# Pass a list of IDs to remove collection from multiple sales channels. #}
{% do RUN_ACTION("collection_unpublish_sales_channels", {
  resource: collection,
  sales_channels: ["gid://shopify/Publication/12341234", "gid://shopify/Publication/98719871"]
}) %}

{#
  Debug info will let you know if the entered IDs are "valid" or "invalid".
  {
    "user_entered_sales_channels": {
        "gid://shopify/Publication/12341234": "valid",
        "gid://shopify/Publication/98719871": "valid"
    },
    "sales_channels": [
        "gid://shopify/Publication/12341234",
        "gid://shopify/Publication/98719871"
    ]
  }
#}

slack

Send a Slack message.

Name Type(s) Description
to string Send to a Slack username formatted as @username or a channel, formatted as #channel.
body string The Slack message to send. Learn more about Slack message formatting.

Example sending a message with an emoji icon and link.

{% do RUN_ACTION("slack", {
  to: "#new-orders",
  body: "Whoop whoop! :moneybag: You've made a sale! <{{ order.admin_url }}|View Order>",
}) %}

trello

Add a card to Trello.

Name Type(s) Description
debug boolean When debug is true, the action will display a list of board IDs when run, or card options if a board_id is set.
board_id string The Trello board ID.
list_id string The specific list ID in the board.
title string The Trello card title.
description string The Trello card description.
due_date string A relative or absolute date and time, such as friday 8AM or 12/31/2021.
labels array An array of label IDs that are specific to the board.
members array An array of members that are specific to the board.
custom_fields hash A hash of custom fields keyed by ID.
attachment array An array of file or link attachment URLs.

If you don't know the current board_id and list_id to use, you can find them in a couple different ways.
To see your Trello board information as JSON you can navigate to a Trello board and add .json to the end of the URL.
For example, if your URL is https://trello.com/b/7Cfi181ca/my-new-orders, go to https://trello.com/b/7Cfi181ca/my-new-orders.json.
In the resulting JSON output you can find the board ID, the list IDs, and the label IDs.

Another method is to use the inline Test Center which can fetch your boards and lists and display them to you.

  1. First, in the Test Center, select a resource (if Test Center is not available in your workflow type then you will need to follow the method listed above).
  2. In the Custom Action, enter the example code below.
  3. When the blue icon appears, hover over it to see the available board IDs.
{# Use the "debug" argument to display board_id information. #}
{% do RUN_ACTION("trello", {
debug: true
}) %}

{# The resulting debug information will be shown: #}
[
  {
     "debug": {
       "instructions": "Enter a "board_id" to view list_id options and label options.",
       "boards": {
         "5e1234659335f61273e62": "My Board One",
         "5b1234cc771d3f3c0c4dd45a": "My Board Two",
         "5f12346b6872c714ef797b52": "My Board Three",
       }
     }
   }
]

Enter a board ID to see available list IDs, label IDs, member IDs, and custom field information in that board.

{# Entering a "board_id" with "debug" will show available lists and labels. #}
{% do RUN_ACTION("trello", {
  debug: true,
  board_id: "5e1234659335f61273e62"
}) %}

{# The resulting debug information will be shown: #}
[
  {
    "debug": {
            "board_id": "Board Name [60590164abedee8ca3012aaa]",
            "title": "Enter a title for your card",
            "description": "Enter a description for your card",
            "due_date": "An optional due date for your card",
            "lists": {
                "60590164abedee8ca301aab": "List one",
                "60590164abedee8ca301aac": "List two",
                "60590164abedee8ca301aad": "List three"
            },
            "labels": {
                "60590452e106b4821ee6f80": "Label 1",
                "6059044cde192c45b714e75": "Label 2",
                "60590164184d2c731bf19a8": "Label 3",
            },
            "members": {
                "6054fc8dd4b7681b92402ad1": "John Smith",
                "6054fc8dd4b7681b92402ad2": "Bob Campbell",
            },
            "custom_fields": {
                "605904e7331b193fe1e61088": {
                    "name": "Text Type",
                    "type": "text"
                },
                "605904efee5989388de7672e": {
                    "name": "Check Box",
                    "type": "checkbox"
                },
                "60590503c6cd893898e1673f": {
                    "name": "Date Test",
                    "type": "date"
                },
                "605b534ffa2ee2891a0f5016": {
                    "name": "Dropdown",
                    "type": "list",
                    "options": {
                        "605b534ffa2ee2891a0f5017": "Option 1"
                        "605b534ffa2ee2891a0f5018": "Option 2"
                        "605b534ffa2ee2891a0f5019": "Option 3"
                    }
                }
            },
            "attachment: {
                "http://path/to/file.png",
                "http://path/to/second/file.jpg",
                "http://path/to/link",
                }

        }
    }
]

You can now configure your action with the correct board_id, list_id, labels (array of label IDs), members (array of member IDs), and a custom_fields hash. All custom field values must be a string.

{% do RUN_ACTION("trello", {
  board_id: "YOUR_BOARD_ID",
  title: "New Order {{ order.name }}",
  description: "Order needs processing by date.",
  list_id: "YOUR_LIST_ID",
  labels: ["YOUR_LABEL_ID_1", "YOUR_LABEL_ID_2"],
  members: ["YOUR_MEMBER_ID_1", "YOUR_MEMBER_ID_2"],
  custom_fields: {
      "YOUR_CUSTOM_FIELD_ID_1":"A text field value",
      "YOUR_CUSTOM_FIELD_ID_2":"true",
      "YOUR_CUSTOM_FIELD_ID_3":"+3 Days",
      "YOUR_CUSTOM_FIELD_ID_4":"YOUR_CUSTOM_FIELD_ID_4"
  },
  attachment: ["http://path/to/file.png", "http://path/to/second/file.jpg", "http://path/to/link"],
  due_date: "+5 weekdays",
}) %}

twilio

Send a SMS message using your Twilio account.

Name Type(s) Description
to string Phone number including country code, ex: 16031238888
body string The message to send.
opt_out string A one time mandatory opt out statement that will be added to the first message. Opt out must contain one of the keywords, such as STOP, UNSUBSCRIBE or CANCEL. Leaving blank will use a default message.

{% do RUN_ACTION("twilio", {
  to: "16031238888",
  body: "The message.",
  opt_out: "Reply STOP to unsubscribe."
}) %}

zapier

Send to Zapier.

Name Type(s) Description
url string Zapier Webhook URL. URL should resemble: https://hooks.zapier.com/hooks/catch/123123/abcdefg/ View Help Documentation
resource object A resource such as a product, order, etc. to send to Zapier as JSON. Leave blank to send a custom payload.
body string A string formatted as JSON for a custom payload. See also: to_json filter above. Leave blank to send a complete resource using the resource parameter above.

{% do RUN_ACTION("zapier", {
  url: "https://hooks.zapier.com/hooks/catch/123123/abcdefg/",
  body: "{test: true}"
}) %}

{% do RUN_ACTION("zapier", {
  url: "https://hooks.zapier.com/hooks/catch/123123/abcdefg/",
  resource: order,
}) %}

google_sheets

Send one or more rows to Google Sheets.

Name Type(s) Description
url string The URL to the Google Sheet, can include the specific tab id. Example: https://docs.google.com/spreadsheets/d/abc123/edit#gid=TAB_ID
rows array A multi-dimensial of rows and cell values.
tab number (optional) The sheet tab ID. Only required if the url does not contain the #gid=TAB_ID fragment.

{% do RUN_ACTION("google_sheets", {
  url: "https://docs.google.com/spreadsheets/d/abc123/edit#gid=TAB_ID",
  rows: [
    ["row_1_A", "row_1_B", "row_1_C"],
    ["row_2_A", "row_2_B", "row_2_C"],
  ]
}) %}

klaviyo_subscribe

Subscribe or update a customer in Klaviyo.

Name Type(s) Description
debug boolean When debug is true, the action will display available list IDs when run. If a list_id is empty the customer will be created or updated only.
list_id string The Klaviyo List ID.
customer object The customer object.
customer_properties hash A keyed hash of customer properties.

{% do RUN_ACTION("klaviyo_subscribe", {
  list_id: "KL123",
  customer: customer,
}) %}

{% do RUN_ACTION("klaviyo_subscribe", {
  list_id: false,
  customer: order.customer,
  customer_properties: {
    first_name: "Overrides the default customer first_name",
    city: "Overrides the default address city",
    CustomProp1: "A custom property.",
    ShopifyTags: order.customer.tags_array,
    CustomCreatedAtDate: order.customer.created_at,
  }
}) %}

klaviyo_track_event

Track a customer event in Klaviyo.

Name Type(s) Description
event string The event name.
customer object The customer object.
event_properties hash A keyed hash of event properties.
customer_properties hash A keyed hash of customer properties.

{% do RUN_ACTION("klaviyo_track_event", {
  customer: order.customer,
  event: "Arigato Example",
  event_properties: {
    foo: "bar",
    tags: order.tags_array,
  },
  customer_properties: {
    CustomProp1: "Hello, World!",
  }
}) %}

mailchimp_subscribe

Subscribe a customer to a Mailchimp list. Note, subscribing to groups is not supported.

Name Type(s) Description
debug boolean When debug is true, the action will display available list IDs when run. If a list_id is set then available merge fields will be displayed
list_id string The Mailchimp List ID.
email string The customer email address.
tags string A string of comma-separated tags.
merge_fields hash A keyed hash of merge field names and values.

{% do RUN_ACTION("mailchimp_subscribe", {
  list_id: "abc12345678",
  email: customer.email,
}) %}

{% do RUN_ACTION("mailchimp_subscribe", {
  list_id: "abc12345678",
  email: customer.email,
  tags: customer.tags,
  merge_fields: {
    FNAME: customer.first_name,
    LNAME: customer.last_name,
    MY_CUSTOM_FIELD_VALUE: "Custom Value!"
    ADDRESS: {
      addr1: customer.default_address.address1,
      addr2: customer.default_address.address2,
      city: customer.default_address.city,
      state: customer.default_address.province_code,
      country: customer.default_address.country_code,
      zip: customer.default_address.zip
    },
  }
}) %}

mailchimp_unsubscribe

Unsubscribe a customer from a Mailchimp list. Note, unsubscribing from groups is not supported.

Name Type(s) Description
debug boolean When debug is true, the action will display available list IDs when run.
list_id string The Mailchimp List ID.
email string The customer email address.

{% do RUN_ACTION("mailchimp_unsubscribe", {
  list_id: "abc12345678",
  email: customer.email,
}) %}

shopify_flow

Send data Shopify Flow for processing

Name Type(s) Description
String One string A string.
String Two string A string.
String Three string A string.
String Four string A string.
String Five string A string.
Number One number A number.
Number Two number A number.
Number Three number A number.
Boolean One boolean A boolean.
Boolean Two boolean A boolean.
Boolean Three boolean A boolean.
URL string A URL.
Email string An email address.

{% do RUN_ACTION("shopify_flow", {
  "String One": "String data 1",
  "String Two": "String data 2",
  "String Three": "String data 3",
  "String Four": "String data 4",
  "String Five": "String data 5",
  "Number One": "Number data 1",
  "Number Two": "Number data 2",
  "Number Three": "Number data 3",
  "Boolean One": true,
  "Boolean Two": false,
  "Boolean Three": true,
  "URL": "https://bonify.io",
  "Email": "support@bonify.io",
}) %}

airtable_insert_record

Insert one record into Airtable

Name Type(s) Description
debug boolean When debug is true, the action will display a list of base IDs when run, or table Ids if a base_id is set. If both base_id and table_id are set, then a list of fields will be displayed.
base_id string The Airtable base ID.
table_id string The specific table ID in the base.
fields hash A hash of field IDs and values to set on the record.

Below are some examples on how to debug for more information on what is available for your Airtable integration. For more field level specific information, visit the Airtable field documentation.

{# Use the "debug" argument to display base_id information. #}
{% do RUN_ACTION("airtable_insert_record", {
  debug: true
}) %}

{# The resulting debug information will be shown: #}
[
    {
        "debug": {
            "instructions": "Enter a "base_id" to view table_id options.",
            "bases": {
                "5e1234659335f61273e62": "Base One",
                "5b1234cc771d3f3c0c4dd45a": "Base Two",
                "5f12346b6872c714ef797b52": "Base Three",
            }
        }
    }
]

{# Use the "debug" argument to display table_id information. #}
{% do RUN_ACTION("airtable_insert_record", {
  debug: true,
  base_id: "5b1234cc771d3f3c0c4dd45a"
}) %}

{# The resulting debug information will be shown: #}
[
    {
        "debug": {
            "base_id": "Base Name [5b1234cc771d3f3c0c4dd45a]",
            "instructions": "Enter a "table_id" to view field options.",
            "tables": {
                "60590164abedee8ca301aab": "Table one",
                "60590164abedee8ca301aac": "Table two",
                "60590164abedee8ca301aad": "Table three"
            }
        }
    }
]

{# Use the "debug" argument to display field information. #}
{% do RUN_ACTION("airtable_insert_record", {
  debug: true,
  base_id: "5b1234cc771d3f3c0c4dd45a",
  table_id: "60590164abedee8ca301aac"
}) %}

{# The resulting debug information will be shown: #}
[
    {
        "debug": {
            "base_id": "Base Name [5b1234cc771d3f3c0c4dd45a]",
            "table_id": "Table Name [60590164abedee8ca301aac]",
            "fields": {
                "Field One": {
                    "id": "605b534ffa2ee2891a0f5017",
                    "type": "Single Line Text"
                },
                "Field Two": {
                    "id": "605b534ffa2ee2891a0f5018",
                    "type": "Rich Text"
                },
                "Field Three": {
                    "id": "605b534ffa2ee2891a0f5019",
                    "type": "Number"
                },
            }
        }
    }
]

Example inserting a record.

{% do RUN_ACTION("airtable_insert_record", {
  base_id: "YOUR_BASE_ID",
  table_id: "YOUR_TABLE_ID",
  fields: {
      "Name": "John Doe",
      "Email": "john@mail.com",
      "Phone": "123-456-7890"
   }
}) %}

Workflow Variables

Workflow Variables

Workflow Variables allow you to store key points of data in a structured format.
Variables are defined as a field type which include:

  • Text: A single-line text field.
  • Text (Multiple-Lines): A text field that supports multiple lines and HTML.
  • Dropdown: A dropdown of options where you can select one value.
  • Radios: A list of radio options where you can select one value.
  • Number: Stores a number value.
  • Checkboxes: Ability to select one or more items.
  • Date: Select a date using a date-picker.
  • JSON: Store any valid JSON object.
  • Key/Value: A structured JSON object that only supports simple key:value pairs.

Workflow Variables can be accessed in your conditions and actions using the workflow_vars object.
You can find Workflow Variable tokens in the Token Browser. Their values can be accessed like this:

{{ workflow_vars["my_text_var"].value }}

Global Variables

Global Variables are similar to Workflow Variables but are globally available in all workflows.

Global Variables can be accessed in your conditions and actions using the global_vars object.
You can find Global Variable tokens in the Token Browser. Their values can be accessed like this:

{{ global_vars["my_text_var"].value }}

Special Variable Types

Most variable fields types, such as Text and Number can be rendered by simply using {{ workflow_vars["my_var_name"].value }}.
However, there are some variable types that need more consideration when rendering.


HTML Values
Any text-based variable that contains HTML can be rendered as raw HTML by using the raw string filter.
For example, given the following value: <strong>This is HTML</strong>

{{ workflow_vars["my_html_string"].value }} {# Will escape HTML characters like: &lt;strong&gt;This is HTML&lt;/strong&gt;  #}
{{ workflow_vars["my_html_string"].value | raw }} {# Prints HTML characters like: <strong>This is HTML</strong>  #}


Checkboxes Variable Type

{{ workflow_vars["my_checkboxes"].value }} {# Prints out a pipe-delimited string of values, such as "1|2|3" #}
{{ workflow_vars["my_checkboxes"].values }} {# An array of values, such as [1, 2, 3] #}
{{ workflow_vars["my_checkboxes"].values | join(', ') }} {# Prints out the values as "1, 2, 3" #}


JSON Variable Type
Given the following JSON string:

{
  "product": {"title": "My Product Title"}
}

{{ workflow_vars["my_json"].value | debug }} {# Prints out the entire parsed JSON object. #}
{{ workflow_vars["my_json"].value.product.title }} {# Prints "My Product Title" #}


Key/Value Variable Type
This variable type is similar to JSON, but more structured and only allows top-level keys, such as:

{
  "vendor_a": "admin@vendor_a.com",
  "Vendor B": "admin@vendor_b.com"
}

{{ workflow_vars["my_kv_field"].value | debug }} {# Prints out the entire parsed JSON object. #}
{{ workflow_vars["my_kv_field"].value.vendor_a }} {# Prints "admin@vendor_a.com" #}
{# If your key contains any spaces or special characters you need to use quoted syntax: #}
{{ workflow_vars["my_kv_field"].value["Vendor B"] }} {# Prints "admin@vendor_b.com" #}


Date Variable Type
The Date type stores a date as a string in whatever format you specify.
However, you can change the format of the date and manipulate it like this:

{{ workflow_vars["date"].value }} {# A date string, such as "2022-01-28" #}
{{ workflow_vars["date"].value | date("m/d/Y") }} {# Prints "1/28/2022" #}
{{ workflow_vars["date"].value | date_modify("+1 year") | date("m/d/Y") }} {# Prints "1/28/2023" #}
Learn more about date filters.

render_variable(variableargs)

Renders a single variable and include its label and description.

Name Type(s) Description
variable object The variable field (either workflow_vars["FIELD"] or global_vars["FIELD"]).
args hash A keyed hash of arguments (see below).
Name Type(s) Description
format string Valid formats include html, plain, markdown, trello, or slack.
label boolean Whether to display the variable label.
description boolean Whether to display the variable description.

{{ render_variable(workflow_vars["test_variable"], {format: 'plain', label: true, description: true ) }}
{# Will print the following: #}
Label: Test Variable
Description: The testing text field.
Value: The value of the variable

render_variables(variablesargs)

Renders all defined variables and can include their labels and descriptions.

Name Type(s) Description
variables object The variables object (either workflow_vars or global_vars).
args hash A keyed hash of arguments (see below).
Name Type(s) Description
format string Valid formats include html, plain, markdown, trello, or slack.
label boolean Whether to display the variable label.
description boolean Whether to display the variable description.

{{ render_variables(workflow_vars, {format: 'plain', label: true, description: true ) }}
{# Will print the following: #}
Label: Test Variable 1
Description: The testing text field.
Value: The value of the variable

Label: Test Variable 2
Description: The second testing text field.
Value: The value of the second variable