Skip to content

Shopify Lookups

The Shopify connector adds the GraphQLLookup function to IMan's scripting. It sends a GraphQL query to a store through a Shopify System Connector and returns one value from Shopify's answer. Call it from any expression to translate a code into a Shopify id, look up a value, or check that a record exists.

GraphQLLookup

Description

Runs a query against Shopify's GraphQL Admin API, version 2026-10, and returns the value at a JPath in the answer.

Syntax

GraphQLLookup( systemid, query, variables, returnpath, mustreturnvalue [, pageinfopath] )

Arguments

  • systemid
    • The ID of the Shopify System Connector to query.
  • query
  • variables
    • The query's variables, as a JSON object, such as {"q": "sku:ABC-100"}. Pass "" for a query without variables.
    • Variables keep the query text the same from record to record. They also save you escaping a value inside the query.
  • returnpath
    • The JPath of the value to return. It starts at the top of Shopify's answer and begins with /data/.
    • A path through a list returns the first element's value, and a query in square brackets picks an element by its fields.
    • The path must end at a value. A path that ends at an object or a list returns an empty string.
  • mustreturnvalue
    • True or False.
    • True: the function raises an error when the path finds no value.
    • False: the function returns an empty value when the path finds no value.
  • pageinfopath
    • Optional. The JPath of the pageInfo object in the answer, for a query that returns more than one page.
    • With it, IMan asks Shopify for each page in turn, and returns the first value the path finds across them. The query must declare a $endCursor: String variable and pass it as the connection's after argument. IMan sets the variable for each page after the first.
    • The query must select hasNextPage and endCursor in pageInfo.

Remarks

IMan keeps each answer for the rest of the transform's run. A later call with the same System Connector, query and variables reads the kept answer and sends nothing to Shopify. A call that changes only the return path also reads it. A lookup therefore does not see a change made in Shopify after its first answer.

The System Connector's app needs the access scope for whatever the query reads, such as read_products for products and variants. See Access Scopes.

When Shopify throttles the query, IMan waits and sends it again. An error in Shopify's answer, such as a field the schema does not have or a missing access scope, raises an error with Shopify's message.

The examples set the query, its variables and the return path first, and call the function on the last line. The last line's result is the field's value.

Example: a variant's id from its SKU

%SKU holds the SKU. The function returns the variant's id, such as gid://shopify/ProductVariant/19523123216406, and raises an error when no variant has the SKU:

Dim Query
Dim Parameters
Dim ReturnPath

Query = "query($q: String) { productVariants(first: 1, query: $q) { nodes { id } } }"
Parameters = "{""q"": ""sku:" & %SKU & """}"
ReturnPath = "/data/productVariants/nodes/id"

GraphQLLookup("SHOPIFY", Query, Parameters, ReturnPath, True)

A SKU with a space or a colon in it needs quotes inside the search. See Shopify's search syntax.

Example: a location's id from its name

The query reads every location, 250 to a page, and the return path picks the location named in %Warehouse. The query and its variables do not change from record to record. IMan reads the locations from Shopify once, and every later record reads the kept answer:

Dim Query
Dim Parameters
Dim ReturnPath
Dim PageInfoPath

Query = "query($endCursor: String) { locations(first: 250, after: $endCursor) { nodes { id name } pageInfo { hasNextPage endCursor } } }"
Parameters = ""
ReturnPath = "/data/locations/nodes[name='" & %Warehouse & "']/id"
PageInfoPath = "/data/locations/pageInfo"

GraphQLLookup("SHOPIFY", Query, Parameters, ReturnPath, True, PageInfoPath)

Example: checking that a customer exists

customerByIdentifier finds a customer by their exact email address, and answers null when there is none. With mustreturnvalue False, the expression is True when the customer exists:

Dim Query
Dim Parameters
Dim ReturnPath

Query = "query($identifier: CustomerIdentifierInput!) { customerByIdentifier(identifier: $identifier) { id } }"
Parameters = "{""identifier"": {""emailAddress"": """ & %Email & """}}"
ReturnPath = "/data/customerByIdentifier/id"

GraphQLLookup("SHOPIFY", Query, Parameters, ReturnPath, False) <> ""

Example: a company location's id from its external id

Dim Query
Dim Parameters
Dim ReturnPath

Query = "query($q: String) { companyLocations(first: 1, query: $q) { nodes { id } } }"
Parameters = "{""q"": ""external_id:" & %AccountRef & """}"
ReturnPath = "/data/companyLocations/nodes/id"

GraphQLLookup("SHOPIFY", Query, Parameters, ReturnPath, True)

CustomLookup

Description

Reads a resource from Shopify's REST Admin API and returns the value at a JPath in the answer. CustomLookup remains for existing integrations. Use GraphQLLookup for new work, because Shopify has made the REST Admin API a legacy API.

Syntax

CustomLookup( systemid, select, from, "", "", mustreturnvalue )

Arguments

  • systemid
    • The ID of the Shopify System Connector to query.
  • select
    • The JPath of the value to return.
  • from
    • The path of the REST resource, such as /admin/locations.json. Leave out the store's address. IMan takes it from the System Connector.
  • The fourth and fifth arguments
    • Not used. Pass "" for each.
  • mustreturnvalue
    • True or False.
    • True: the function raises an error when the lookup returns no value.
    • False: the function returns an empty string when the lookup returns no value.

Example

The id of the store's first location:

CustomLookup("SHOPIFY", "/locations/id", "/admin/locations.json", "", "", False)

The id of the location named New York:

CustomLookup("SHOPIFY", "/locations[name='New York']/id", "/admin/locations.json", "", "", False)