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.
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.

An example

Find a variant by SKU, as the templates do:

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

Variables (JSON):

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

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

{{ 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-10 (default) and 2026-07 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.
• The ids a mutation changed are noted for Loop protection.

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.
• 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.
• Idempotency keys. Shopify refuses 16 mutations without an idempotency key: setting, adjusting, moving and activating inventory, inventory transfers and shipments, activating and deactivating a location, and refundCreate. A mutation picked from the list comes prepared with @idempotent(key: $idempotencyKey) and an empty "idempotencyKey": "" in the variables. Leave it empty: the step fills in one key per run and step, and per item inside Repeat for each, so a retry is applied once. A key you write yourself is used as it is. A mutation you write by hand without @idempotent still gets Shopify's error.
• Customer and order data is protected customer data. See Permissions and store data access.
• Script tag mutations and queries are not listed. Shopify is retiring script tags, and the app does not ask for that permission.