Shopifex.API (Shopifex v3.0.0)

Copy Markdown View Source

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

api_version()

@spec api_version() :: String.t()

The configured Shopify Admin API version. Defaults to "2026-07".

graphql(shop, query, variables \\ %{})

@spec graphql(struct(), String.t(), map()) :: {:ok, map()} | {:error, term()}

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 errors list (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