Shopify Storefront

Shopify's Storefront GraphQL API — one action per Query/Mutation for product browsing, the Cart API, customer accounts, search, and content. Covers the shared connection, the editable query / Variables model, global ids and @inContext, the Cart API and customer-account flows, and the two-level data / errors / userErrors response. Every action is documented in the action reference.

Open in Claude

Browse 71 Shopify Storefront actions Article · Articles · Blog · Blogs · Cart · Collection · +20 more

On this page

What this connector is Connecting How the actions work Reading the response Working with ids and localization The Cart API Customer accounts Not sure which action?Step Name Step Reference Execution Settings Caching Locking

What this connector is

The Shopify Storefront API is the public, customer-facing GraphQL API that powers headless storefronts: browsing products and collections, the Cart API, customer accounts, search, content (blogs, articles, pages, metaobjects), and localization. It is a different API from the Shopify connector (which wraps the Admin GraphQL API) — no store management here (products can be read but not created, orders aren't exposed).

This connector is generated from Shopify's published Storefront GraphQL schema (version 2026-07) — one action per Query or Mutation root field. Deprecated fields (the *ByHandle queries) are left out; use the handle argument on product / collection / blog / page instead.

Browse every action, grouped by resource, in the action reference. Each action page shows its default query, typed variables with an example, and the response fields.

Connecting

Every action uses a Shopify Storefront connection:

Shop Domain — your .myshopify.com domain, without https://.
Storefront API Access Token — a Storefront access token (not an Admin token), from your Shopify admin under Settings → Apps and sales channels → Develop apps → your app → API credentials → Storefront API access token.

The token is sent as the X-Shopify-Storefront-Access-Token header and the endpoint (https://<shop-domain>/api/2026-07/graphql.json) is filled in from the connection automatically.

How the actions work

Each action wraps one GraphQL operation:

GraphQL Query — the query/mutation document, pre-filled and fully editable. The generated selection set is nested up to 3 levels and leaves out fields that take their own arguments — edit it to add connection pages (products(first: 10) { edges { node { … } } }), pageInfo { hasNextPage endCursor }, price fields, or an @inContext directive.
Variables — one multi-line field for the whole variables object, with the usual parameter picker to wire in values with {{<stepReference>.field.path}}. It is pre-filled with a skeleton of every declared argument ($cartId: ID! → "cartId": ""). Once references resolve it must be valid JSON.
Endpoint — pre-filled from the connection; override only to point at a different shop or API version.
Additional Headers, Forward All Headers — as on every connector.

If you edit the query to add or rename variables, keep Variables in sync — they are sent together as { query, variables }.

Reading the response

The body is the raw GraphQL HTTP response, so there are two levels of data. See Step Reference.

The operation result — {{<stepReference>.response.data.data.<fieldName>}}. A step named "List Products" (reference listProducts) running the products query resolves its edges at {{listProducts.response.data.data.products.edges}} and the next-page flag at {{listProducts.response.data.data.products.pageInfo.hasNextPage}} — once you've added edges/pageInfo to the query.
GraphQL errors — a top-level errors array (unknown field, invalid token, malformed query) fails the step, even though the HTTP status is 200. Details at {{<stepReference>.response.data.errors}}; turn on Continue on Error to inspect and branch.
userErrors — cart mutations return { cart, userErrors, warnings } and customer mutations return { ..., customerUserErrors }. Business failures (out-of-stock variant, wrong password, invalid address) land there, not in errors, and do not fail the step: {{<stepReference>.response.data.data.<mutationName>.userErrors}}. Check them before assuming a write worked.
Rate limiting — a throttled response is treated as a retryable rate-limit error and retried with backoff automatically.

Cursor pagination: add pageInfo { hasNextPage endCursor } to a connection's selection set, then pass endCursor back as the after variable.

Working with ids and localization

Global ids — gid://shopify/Product/123, gid://shopify/Cart/abc, gid://shopify/ProductVariant/456 — everywhere, never bare numbers. Products, collections, blogs, and pages can also be fetched by handle.
@inContext — money and availability on the Storefront API are context-sensitive. To get market-specific prices or translated content, add the directive to the operation line of the GraphQL Query, e.g. query Products($first: Int!) @inContext(country: CA, language: FR) { … }. The generator does not add it.

The Cart API

Carts are the Storefront checkout primitive. Typical flow:

cartCreate — input: { lines: [{ merchandiseId: "gid://shopify/ProductVariant/…", quantity: 1 }] }. Read the id from {{createCart.response.data.data.cartCreate.cart.id}} and the hosted checkout URL from …cartCreate.cart.checkoutUrl.
cartLinesAdd / cartLinesUpdate / cartLinesRemove — cartId plus lines (lineIds for remove).
cartBuyerIdentityUpdate — attach email, phone, country, or a customer access token.
cartDiscountCodesUpdate — the array replaces the current set; [] clears it.
cartPrepareForCompletion → cartSubmitForCompletion — completes the cart server-side; poll the cartCompletionAttempt query for the result.

Customer accounts

A customer access token identifies a logged-in shopper. customerAccessTokenCreate (input: { email, password }) returns { customerAccessToken { accessToken expiresAt }, customerUserErrors }; pass the accessToken as the customerAccessToken variable to customer, customerUpdate, and the customerAddress* mutations.

Not sure which action?

Open the action reference and search or filter by resource (Cart, Customer, Product, …). Action names are the GraphQL field names exactly. The most common actions:

Browse: products, product, collection, search, predictiveSearch, productRecommendations
Cart: cart, cartCreate, cartLinesAdd, cartLinesUpdate, cartLinesRemove, cartSubmitForCompletion
Customers: customerAccessTokenCreate, customerCreate, customer

Also applies here

Step Name

What it's for

Every step in a workflow gets a name — either one you set or a default based on the connector and action (e.g. "Get Order Details", "Send Welcome Email"). It's shown throughout the UI and in your execution history, and it's also the source for the step's Reference — a camelCase identifier auto-generated from the name (e.g. "Get Order Details" → getOrderDetails) — which is what you actually use in {{...}} expressions to read this step's output from later steps. See Step Reference.

Rules

Must be at least 2 characters, and 50 characters or fewer.
Must be unique within the workflow — reusing a name that's already taken will be rejected, with a suggested alternative (e.g. "Get Order Details 2").
Can't be empty.

Tips

Prefer a descriptive, human-readable name over a generic one — "Get Order Details" is easier to work with later than "HTTP Request 2", especially once a workflow has a dozen steps.
Renaming a step updates every reference to it elsewhere in the workflow automatically.

Step Reference

Syntax

Any input field can reference earlier data using {{expression}}. The expression is evaluated as JSONata — so simple dot-paths and more advanced queries (filters, functions) both work.

Referencing a step's output

Use the step's Reference — a camelCase identifier auto-generated from its Name (e.g. "Get Order Details" → getOrderDetails), shown read-only wherever the step's fields are configured — followed by the field path. Elsewhere in these docs this general pattern is written as {{<stepReference>.field.path}}:

text

{{getOrderDetails.response.data.id}}
{{getOrderDetails.response.status}}

The raw display name won't work here even though it's what you see in the UI — {{Get Order Details.response.data.id}} isn't valid, since a bare name containing spaces isn't a single JSONata identifier. Always use the camelCase Reference.

You can also reference steps by position instead of by reference:

text

{{steps[0].response.data.id}}

Referencing trigger data

text

{{trigger.headers.authorization}}
{{trigger.body.customerId}}
{{trigger.query.page}}
{{trigger.params.orderId}}
{{trigger.method}}
{{trigger.path}}

Referencing workflow variables

text

{{variables.myVariable}}

See Variables for the full list of variable types and more examples, including connection-type variables.

Referencing runtime variables

A separate, mutable namespace written by the Variable connector while a run is in progress — not the same as the workflow-level variables above:

text

{{runtimeVariables.myVariable}}

Notes

If an expression can't be resolved (a typo in a step name, a field that doesn't exist), it resolves to an empty string rather than failing the workflow — check your execution history if a value comes through blank.
Object values are automatically JSON-stringified when interpolated into a string field.

Execution Settings

Fire-and-forget

When enabled, the workflow doesn't wait for this step to complete before moving to the next one. Use it for steps whose result nothing downstream depends on — logging, analytics, notifications — so they don't add latency to the steps that matter.

Continue on error

When enabled, a failure in this step doesn't stop the workflow — execution continues to the next step. The failure is still recorded in the execution history; this just controls whether it's fatal.

Combine the two for steps that are genuinely optional to the outcome: fire-and-forget so they don't add latency, continue-on-error so a failure in them (e.g. an analytics endpoint being briefly down) doesn't take down an otherwise-successful workflow run.

Caching

What it does

When enabled, a step's result is cached for a configurable TTL (time-to-live, in seconds). If the step runs again with the same effective cache key before the TTL expires, the cached result is returned instead of re-running the step.

Configuring it

Enabled — turn caching on or off for this step.
TTL — how long (in seconds) a cached result stays valid.
Cache key template — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same call". By default this is based on the step's resolved input; a custom template lets you cache more narrowly or broadly than that.

When to use it

Good candidates are steps that call something slow or rate-limited but return the same answer for the same input within a short window — a lookup against a rarely-changing external system, for example. Skip it for steps whose result must always be fresh (anything involving live inventory, pricing, or payment state).

Locking

What it does

When enabled, only one execution of this step (for a given lock key) can run at a time. If a second execution tries to run the same step while a lock is held, it waits until the lock is released or the hold period elapses.

Configuring it

Enabled — turn locking on or off for this step.
Lock key — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same resource". By default the lock is scoped to the step itself; a custom key lets you lock per-customer, per-order, or any other identifier that needs serialized access.
Period — how long (in seconds) the lock is held before it's automatically released, in case an execution doesn't complete normally.

When to use it

Use it whenever concurrent executions could race on the same resource — e.g. two workflow runs both trying to update the same order's status at once. A lock key scoped to the order id ensures only one of them proceeds at a time.

Was this page helpful?

Last updated 9 October 2026