Shopify QL API
The ShopifyQL API checks whether analytics is available to the current user. Use it to decide what your app shows before you render analytics web components.
Metric cards wait for initialization on their own, so you don't need to call this API to render a card. If analytics isn't available and your app doesn't check, then each card shows a generic error.
Anchor to Use casesUse cases
- Custom unavailable state: Show your own message, empty state, or fallback content instead of the metric card's generic error.
- Loading state: Show a loading indicator while analytics initializes.
- Conditional sections: Hide an analytics section from users who can't view analytics.
Anchor to MethodsMethods
The API is available on the shopify global. All methods are asynchronous and return a Promise.
- Anchor to availableavailableavailable() => Promise<boolean>() => Promise<boolean>requiredrequired
Checks whether analytics is available to the current user. Resolves to
truewhen analytics is available, andfalsewhen it isn't, for example, when the user doesn't have permission to view analytics. Afalseresult doesn't include the reason.
js
Examples
Check whether analytics is available
Description
Check whether the current user can view analytics. The returned value is a boolean.
js
const isAvailable = await shopify.shopifyQL.available(); // => trueShow a custom unavailable state
Description
Show a loading state while the check is pending. Then render a metric card when analytics is available, or your own message when it isn't.
html
<p id="loading">Loading analytics…</p> <p id="unavailable" hidden>Analytics isn't available.</p> <div id="analytics"></div> <template id="analytics-template"> <s-shopifyql-metric-card heading="Total sales" query="FROM sales SHOW total_sales VISUALIZE total_sales TYPE line" ></s-shopifyql-metric-card> </template> <script> async function showAnalytics() { try { const isAvailable = await shopify.shopifyQL.available(); if (isAvailable) { const template = document.getElementById('analytics-template'); document.getElementById('analytics').append(template.content.cloneNode(true)); } else { document.getElementById('unavailable').hidden = false; } } catch (error) { document.getElementById('unavailable').hidden = false; console.error(error); } finally { document.getElementById('loading').hidden = true; } } showAnalytics(); </script>