---
title: "Every Shopify mutation and query - Workflow Suite"
description: "Pick any mutation or query of the Shopify Admin API from a searchable list, with its docs link, arguments, needed permissions and API version."
canonical: "https://docs.workflow-suite.app/shopify-mutations-and-queries"
---

# Every Shopify mutation and query

When no ready-made action fits, a workflow can call the Shopify Admin API directly. You do not need to know the API by heart: the step picker lists **every mutation** (what changes store data) and **every query** (what reads it), fills in the step for you and links to Shopify's documentation.

The step behind both is **Shopify Admin API (GraphQL)**.

## Change store data: pick a mutation

1. Press **+** and select **Shopify** in **Add a step**.
2. Below the ready-made actions, **All Admin API mutations** lists the mutations by category. Search by what you want to do, by name or by permission, for example `refundCreate` or `write_orders`.
3. A row that says **Simple form available** has a ready-made action that does the same with less work. See [Ready-made Shopify actions](https://docs.workflow-suite.app/shopify-actions.md).
4. Pick a mutation. The step is added with the mutation's required fields prepared.
5. Fill in **Variables (JSON)**. Add the `json` filter to text values.

## Read store data: pick a query

1. Press **+** and select **Get Shopify data**.
2. Search, for example `orders`, `productVariants` or `read_customers`, and pick a query.
3. The step is filled in with the query's arguments and the most used fields. Add or remove fields in **Query or mutation**.

The docs box under the query lists the **filters** of its search, for example `status:active created_at:>2026-01-01`, and the **fields** of an item you can add.

## The docs box

Under the query or mutation, the step shows what it found out about it:

- **View docs** opens Shopify's documentation of exactly this mutation or query.
- **Access** and the permissions it needs. **This mutation needs a permission** comes with a button to the Permissions page.
- **Arguments**, with **Required** marked and the required fields of input objects.
- What it **returns**, and how later steps read it.
- **Deprecated**, **New in** or **Removed after** a version, when that applies.

A badge under the editor says whether the step changes something: **Mutation: this step changes store data** or **Query: this step only reads**.

> [!WARNING]
> **Some permissions cannot be requested**
> A few mutations need a permission that Shopify does not let this app request, or only hands out on application: for example subscription contracts, taxes, payment mandates and some Shopify Payments tools. The docs box then says **This app cannot request that permission**, and the step would fail when it runs. The picker still lists these mutations so you know where you stand.

## An example

Find a variant by SKU, as the templates do:

```graphql
query ($q: String!) {
  productVariants(first: 1, query: $q) {
    nodes { id sku displayName inventoryItem { id } product { id title } }
  }
}
```

**Variables (JSON)**:

```liquid
{ "q": {{ event.payload.body.sku | prepend: "sku:" | json }} }
```

Later steps read the answer under the step's output. The shape follows your query:

```liquid
{{ steps.variant.output.productVariants.nodes[0].id }}
```

In a Condition, the same value is the path `steps.variant.output.productVariants.nodes.0.id`. Run a **Test** once: afterwards the variable picker offers the real fields of the answer.

## The Admin API version

Shopify releases a new API version every quarter. Each workflow chooses one, under **Shopify Admin API version**: in the docs box, in the pickers and in the **Variables** panel.

- **2026-07 (default)** and **2026-10** are available. A version Shopify has not released yet is marked **(release candidate)** and can still change until its release date.
- The version applies to this workflow's Shopify Admin API (GraphQL) steps and Liquid script steps, and to what the pickers list. Ready-made actions and code steps always use the default version.
- If a mutation does not exist in the workflow's version, the docs box warns you: the step would fail when it runs. Change the version or use another mutation.

## What happens when it runs

- The call runs with the permissions you granted on the Permissions page.
- **Queries run in a preview. Mutations are previewed**: the step reports the mutation and its variables, and changes nothing.
- `userErrors` in a mutation's answer fail the step, with Shopify's message.
- A throttled or unreachable Shopify is tried again automatically. A mutation is only repeated when Shopify did not run it. See [Automatic retries](https://docs.workflow-suite.app/automatic-retries.md).
- The ids a mutation changed are noted for [Loop protection](https://docs.workflow-suite.app/loop-protection.md).

## Good to know

- A query reads **one page** of results: `first: 50` means at most 50. For a job over a whole store, work in portions. See [Schedules](https://docs.workflow-suite.app/schedules.md).
- Shopify meters the API by query cost. Ask only for the fields you use.
- Some mutations have rules that only show at run time. Since API version 2026-04, inventory mutations need an idempotency key, for example. The ready-made inventory actions take care of that; with the raw mutation, follow Shopify's docs behind **View docs**.
- Customer and order data is protected customer data. See [Permissions and store data access](https://docs.workflow-suite.app/permissions-and-store-data-access.md).