---
title: ShopifyQL API
description: >-
  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.
api_version: v1.0
source_url:
  html: 'https://shopify.dev/docs/api/analytics-ui/latest/apis/shopifyql-api'
  md: 'https://shopify.dev/docs/api/analytics-ui/latest/apis/shopifyql-api.md'
api_name: analytics-ui
---

# ShopifyQL 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.

### Use 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.

### Methods

The `shopifyQL` API is available on the `shopify` global. All methods are asynchronous and return a Promise.

* **available**

  **() => Promise\<boolean>**

  **required**

  Checks whether analytics is available to the current user. Resolves to `true` when analytics is available, and `false` when it isn't, for example, when the user doesn't have permission to view analytics. A `false` result doesn't include the reason.

### Examples

* #### Check whether analytics is available

  ##### Description

  Check whether the current user can view analytics. The returned value is a boolean.

  ##### js

  ```js
  const isAvailable = await shopify.shopifyQL.available();
  // => true
  ```

* #### Show 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

  ```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>
  ```

***
