Shopify GraphQL Admin API transport.
This is the library's single chokepoint for Admin API calls. Every request
goes through graphql/3, which keeps expiring offline access tokens fresh:
- Proactive refresh before the call (
Shopifex.Auth.fresh_token/1): if the token will expire within ~5 minutes, refresh now so the request doesn't race the expiry. - Reactive refresh after a 401 (
Shopifex.Auth.refresh/1): if Shopify rejects the token anyway (e.g. revoked early), refresh once and retry the request once.
This is the strategy Shopify explicitly recommends: https://shopify.dev/changelog/offline-access-tokens-now-support-expiry-and-refresh
Error propagation
A refresh failure only short-circuits the request when it's terminal
(Shopifex.Auth.terminal_refresh_error?/1) — a refresh token that's
expired, missing, or rejected outright by Shopify. In that case graphql/3
returns {:error, {:token_refresh_failed, reason}} without sending the
GraphQL request at all:
- Proactive terminal failure: no request is sent.
- Reactive terminal failure (refresh after a 401): the same tuple is
returned instead of the raw
{:error, {401, body}}.
A transient refresh failure (e.g. :refresh_in_progress, a 5xx from
Shopify's token endpoint, or a transport error) doesn't block the request:
it's sent with whatever token the shop currently has. The one exception is
:refresh_in_progress, which also keeps the reactive 401 retry armed,
since another process might finish the refresh before this request's
token is checked. Any other transient failure disarms the reactive retry
(it would just repeat the same failing attempt), so a 401 in that case
returns the plain {:error, {401, body}}.
What lives here vs. in your app
This module ships only the transport. App-specific queries and mutations
(products, inventory, metafields, …) belong in your application — call
Shopifex.API.graphql/3 from there. The library itself only uses this
transport for webhook subscription and billing mutations.
API version
The Admin API version is configurable and defaults to "2026-07":
config :shopifex, :api_version, "2026-07"api_version/0 is the single source of truth — webhook and billing code
read it too.
Summary
Functions
The configured Shopify Admin API version. Defaults to "2026-07".
Run a GraphQL query/mutation against the shop's Admin API.
Functions
@spec api_version() :: String.t()
The configured Shopify Admin API version. Defaults to "2026-07".
Run a GraphQL query/mutation against the shop's Admin API.
Returns {:ok, data} on success, or {:error, reason} where reason is
one of:
- the GraphQL
errorslist (HTTP 200 with partial failure) - a
{status, body}tuple for a non-200/401 response, or a 401 that survived the reactive refresh retry - a transport error (e.g.
%Req.TransportError{}) {:token_refresh_failed, reason}when a terminal token refresh failure stopped the request — see the moduledoc's "Error propagation" section