Execute GraphQL request

This Workflow Companion action allows you to execute GraphQL queries and mutations against the Shopify Admin API (version 2026-10) directly from your workflows.

Explore available queries and mutations in the GraphQL Admin API reference.

Configuration

When configuring this action in your workflow, you'll work with two main components:

Action Configuration

Click the Configure button to open the GraphQL editor
Write your GraphQL query or mutation with full autocomplete support
The editor suggests available fields as you type
Syntax validation helps catch errors before saving

Action Fields

Variables: Enter JSON variables for your GraphQL query in this field. You can use workflow data and variables from previous steps.

JSON format example:

{
  "orderId": "{{ order.id }}",
  "tags": ["urgent", "vip-customer"],
  "updateNote": "Updated by Workflow Companion"
}

API permissions management

If your GraphQL request requires API permissions that haven't been granted to the Workflow Companion app, you'll receive an Access denied error.

To manage permissions:

Click the Manage permissions button above the GraphQL editor
A modal will open showing all available Shopify API scopes
Already granted permissions are marked with a Granted badge
Select the permissions you need by checking the boxes
Click Request selected scopes to initiate the permission request
Follow Shopify's prompts to approve the permissions

Once permissions are granted, you can execute your GraphQL request successfully.

A field can need a permission besides its resource's: a discount's rollouts, which say which rollouts change it and when, need read_rollouts as well as read_discounts.

Mutation requirements

Mutations can optionally include the userErrors { field message } selection. Adding these fields lets the action detect GraphQL errors and fail the workflow when userErrors is not empty. If you omit them, the action cannot read the errors from the response and the workflow will continue even if the mutation returned issues.

Example:

mutation returnClose($id: ID!) {
  returnClose(id: $id) {
    return {
      # Return fields
    }
    userErrors {
      field
      message
    }
  }
}

Data transformation

You can enable Transform response data with JavaScript to reshape the response before it is returned to the workflow. This is useful when the raw response is too large for Shopify Flow's 50 KB payload limit (you may see a "Response too large" error). Trim it down to the fields you actually need so the response fits within the limit.

When enabled, you can write a JavaScript function like this:

export default function ({ data, variables }) {
  // transformation code
  return {
    /* your transformed data */
  };
}

The function may return either a string or any JSON-serialisable value. The input parameter is an object with the following properties:

data: The data field of the GraphQL response.
variables: The variables that were sent with the GraphQL request.

For mutations, the userErrors check (see above) runs before the transform — if the mutation reports errors, the workflow fails and the transform is not invoked.

Output

The action returns the response payload as a JSON string in the data property. When the transform is enabled, this is the value returned by the transform function; otherwise it is the raw data field of the GraphQL response. You can parse this string using the Run code action. The parsed values can then be referenced in subsequent workflow steps using standard variable syntax.

Shipping settings and market-driven shipping

Shopify is moving stores to market-driven shipping: a store's shipping settings move from delivery profiles into its markets. Once a store uses market-driven shipping, the delivery profile fields of the Admin API — deliveryProfile, deliveryProfiles, ProductVariant.deliveryProfile, and the deliveryProfileCreate, deliveryProfileUpdate and deliveryProfileRemove mutations — no longer show or change the live shipping settings: a read returns an outdated copy, and a mutation changes nothing.

So that a workflow never goes on with outdated shipping settings, this action fails a request that uses one of these fields once the store uses market-driven shipping, and says so in the error. Before the switch, such a request runs as usual.

On a store with market-driven shipping, read shipping settings from the store's markets with Market.delivery, and change them with the marketUpdate mutation. Reading markets needs the read_markets permission and changing them needs write_markets (see API permissions management). Shopify's guide Upgrade your app for market-driven shipping describes the new model.

A workflow that works before and after the switch

A store can switch to market-driven shipping at any time. A workflow that checks which model the store uses keeps working through the switch:

Add an Execute GraphQL request step with this query, and turn on Transform response data with JavaScript:

query {
  shop {
    features {
      marketDrivenShipping
    }
  }
}

export default function ({ data }) {
  return String(data.shop.features.marketDrivenShipping);
}

The step's data output is then true or false.

Add a Condition that checks whether that step's data is equal to true.

On the Then branch, add an Execute GraphQL request step that reads the markets' shipping settings, for example:

query {
  markets(first: 10) {
    nodes {
      name
      delivery {
        shipping {
          isEnabled
        }
      }
    }
  }
}

On the Otherwise branch, keep your existing request through deliveryProfiles.