Core Concepts
Techniques
Shopify
The Shopify action sends requests to the Shopify admin API. It supports both REST and GraphQL requests.
In Mechanic, writing data to Shopify must happen using an action. While the Shopify action is usually the right choice, the HTTP action can also be used for this purpose, by manually configuring authentication headers.
Options
This action has several usage styles, each with a different set of constraints on action options.
GraphQL
This usage style invokes the Shopify GraphQL Admin API. In this style, a single GraphQL query string is supplied as the action options. The action tag has specific support for this action type, allowing this string to be provided as the contents of an action block.
Liquid
JSON
1
{% action "shopify" %}
2
mutation {
3
customerCreate(
4
input: {
5
email: "[email protected]"
6
}
7
) {
8
customer {
9
id
10
}
11
userErrors {
12
field
13
message
14
}
15
}
16
}
17
{% endaction %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": "\n mutation {\n customerCreate(\n input: {\n email: \"[email protected]\"\n }\n ) {\n customer {\n id\n }\n userErrors {\n field\n message\n }\n }\n }\n"
5
}
6
}
Copied!
GraphQL with variables
This usage style invokes the Shopify GraphQL Admin API, and supports combining GraphQL queries with GraphQL variables. This can be useful for re-using queries with multiple inputs, and is critical when dealing with very large pieces of input. Because GraphQL queries (excluding whitespace) are limited in length to 50k characters, GraphQL variables can be used in cases when large inputs (like Base64-encoded images) need to be submitted.
Option
Description
queryRequired; a string containing a GraphQL query
variablesRequired; a JSON object mapping variable names to values
Basic example
Liquid
JSON
1
{% capture query %}
2
mutation DeleteProduct($productId: ID!) {
3
productDelete(
4
input: {
5
id: $productId
6
}
7
) {
8
userErrors {
9
field
10
message
11
}
12
}
13
}
14
{% endcapture %}
15
16
{% action "shopify" %}
17
{
18
"query": {{ query | json }},
19
"variables": {
20
"productId": "gid://shopify/Product/1234567890"
21
}
22
}
23
{% endaction %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": {
5
"query": "\n mutation DeleteProduct($productId: ID!) {\n productDelete(\n input: {\n id: $productId\n }\n ) {\n userErrors {\n field\n message\n }\n }\n }\n",
6
"variables": {
7
"productId": "gid://shopify/Product/1234567890"
8
}
9
}
10
}
11
}
Copied!
Complex example
This example shows how the query and variables may be built up separately, and provided to the action using concise tag syntax.
Liquid
JSON
1
{% capture query %}
2
mutation SetCustomerMetafield(
3
$customerId: ID!
4
$metafieldNamespace: String!
5
$metafieldKey: String!
6
$metafieldId: ID
7
$metafieldValue: String!
8
) {
9
customerUpdate(
10
input: {
11
id: $customerId
12
metafields: [
13
{
14
id: $metafieldId
15
namespace: $metafieldNamespace
16
key: $metafieldKey
17
type: "single_line_text_field"
18
value: $metafieldValue
19
}
20
]
21
}
22
) {
23
userErrors {
24
field
25
message
26
}
27
customer {
28
metafield(
29
namespace: $metafieldNamespace
30
key: $metafieldKey
31
){
32
id
33
}
34
}
35
}
36
}
37
{% endcapture %}
38
39
{% assign customer_id = 700837494845 %}
40
{% assign customer = shop.customers[customer_id] %}
41
{% assign existing_metafield = customer.metafields.test | where: "key", "test" | first %}
42
43
{% assign variables = hash %}
44
{% assign variables["customerId"] = customer.admin_graphql_api_id %}
45
{% assign variables["metafieldNamespace"] = "test" %}
46
{% assign variables["metafieldKey"] = "test" %}
47
{% assign variables["metafieldId"] = existing_metafield.admin_graphql_api_id %}
48
{% assign variables["metafieldValue"] = "now" | date: "%s" %}
49
50
{% action "shopify" query: query, variables: variables %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": {
5
"query": "\n mutation SetCustomerMetafield(\n $customerId: ID!\n $metafieldNamespace: String!\n $metafieldKey: String!\n $metafieldId: ID\n $metafieldValue: String!\n ) {\n customerUpdate(\n input: {\n id: $customerId\n metafields: [\n {\n id: $metafieldId\n namespace: $metafieldNamespace\n key: $metafieldKey\n valueType: STRING\n value: $metafieldValue\n }\n ]\n }\n ) {\n userErrors {\n field\n message\n }\n customer {\n metafield(\n namespace: $metafieldNamespace\n key: $metafieldKey\n ){\n id\n }\n }\n }\n }\n",
6
"variables": {
7
"customerId": "gid://shopify/Customer/700837494845",
8
"metafieldNamespace": "test",
9
"metafieldKey": "test",
10
"metafieldId": "gid://shopify/Metafield/18788961353789",
11
"metafieldValue": "1615244317"
12
}
13
}
14
}
15
}
Copied!
Resourceful REST
This usage style invokes the Shopify REST Admin API. It accepts an array of option values, containing these elements in order:
- 1.Operation Must be one of
"create","update", or"delete". - 2.Resource specification When creating, use a single string (e.g.
"customer"). When updating or deleting, use an array (e.g.["customer", 123]). - 3.An object of attributes Only applies to creating and updating.
Example: Creating a resource
This example creates a (minimal) customer record.
Liquid
JSON
1
{% action "shopify" %}
2
[
3
"create",
4
"customer",
5
{
6
"email": "[email protected]"
7
}
8
]
9
{% endaction %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": [
5
"create",
6
"customer",
7
{
8
"email": "[email protected]"
9
}
10
]
11
}
12
}
Copied!
Example: Updating a resource
This example appends a line to the order note (assuming a task subscription to shopify/orders/create).
Liquid
JSON
1
{% action "shopify" %}
2
[
3
"update",
4
[
5
"order",
6
{{ order.id | json }}
7
],
8
{
9
"note": {{ order.note | append: newline | append: newline | append: "We're adding a note! 💪" | strip | json }}
10
}
11
]
12
{% endaction %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": [
5
"update",
6
[
7
"order",
8
3656038711357
9
],
10
{
11
"note": "[customer-supplied note]\n\nWe're adding a note! 💪"
12
}
13
]
14
}
15
}
Copied!
Example: Deleting a resource
This example deletes a product, having a certain ID.
Liquid
JSON
1
{% action "shopify" %}
2
[
3
"delete",
4
["product", 4814813560893]
5
]
6
{% endaction %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": [
5
"delete",
6
[
7
"product",
8
4814813560893
9
]
10
]
11
}
12
}
Copied!
Explicit REST
This usage style invokes Shopify REST Admin API. It accepts an array of option values, containing these elements in order:
- 1.Operation Must be one of
"get","post","put", or"delete" - 2.Request path The entire, literal request path to use, including the requested API version — e.g.
"/admin/api/2020-01/orders.json" - 3.A JSON object of attributes In general, this means a wrapper object whose key is named after the current resource type, and whose value is the same set of data that would be used in the resourceful style
When switching from resourceful to explicit REST, it's common to forget the outer wrapper object. This wrapper is required by Shopify for all request methods except GET and DELETE; it's handled automatically during resourceful usage, but must be handled manually during explicit usage.
Example: Creating a resource
This example creates a (minimal) customer record.
Liquid
JSON
1
{% action "shopify" %}
2
[
3
"post",
4
"/admin/api/2020-01/customers.json",
5
{
6
"customer": {
7
"email": "[email protected]"
8
}
9
}
10
]
11
{% endaction %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": [
5
"post",
6
"/admin/api/2020-01/customers.json",
7
{
8
"customer": {
9
"email": "[email protected]"
10
}
11
}
12
]
13
}
14
}
Copied!
Example: Updating a resource
This example appends a line to the order note (assuming a task subscription to shopify/orders/create).
Liquid
JSON
1
{% action "shopify" %}
2
[
3
"put",
4
"/admin/api/2020-01/orders/{{ order.id }}.json",
5
{
6
"order": {
7
"note": {{ order.note | append: newline | append: newline | append: "We're adding a note! 💪" | strip | json }}
8
}
9
}
10
]
11
{% endaction %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": [
5
"put",
6
"/admin/api/2020-01/orders/3656063189053.json",
7
{
8
"order": {
9
"note": "We're adding a note! 💪"
10
}
11
}
12
]
13
}
14
}
Copied!
Example: Deleting a resource
This example deletes a product, having a certain ID.
Liquid
JSON
1
{% action "shopify" %}
2
[
3
"delete",
4
"/admin/api/2020-01/products/4814813724733.json"
5
]
6
{% endaction %}
Copied!
1
{
2
"action": {
3
"type": "shopify",
4
"options": [
5
"delete",
6
"/admin/api/2020-01/products/4814813724733.json"
7
]
8
}
9
}
Copied!
Last modified 4d ago
Copy link
Edit on GitHub