Choose a version:

currentAppInstallation

query

Returns the AppInstallation for the currently authenticated app. Provides access to granted access scopes, active AppSubscription objects, and billing information for your app.

Use this query to check which permissions your app has, monitor subscription status, or retrieve AppCredit objects. Learn more about managing access scopes, subscription billing, and app credits.

Anchor to Possible returnsPossible returns

Anchor to AppInstallationAppInstallation •AppInstallation!: An app installed on a shop. Each installation tracks the permissions granted to the app through AccessScope objects, along with billing subscriptions and Metafield objects.

The installation provides metafields that only the owning App can access. These metafields store app-specific configuration that merchants and other apps can't modify. The installation also provides URLs for launching and uninstalling the app, along with any active AppSubscription objects or AppPurchaseOneTime purchases.

Was this section helpful?

Examples

Get a list of access scopes

Query

query AccessScopeList {
  currentAppInstallation {
    accessScopes {
      handle
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query AccessScopeList { currentAppInstallation { accessScopes { handle } } }"
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query AccessScopeList {
    currentAppInstallation {
      accessScopes {
        handle
      }
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query AccessScopeList {
    currentAppInstallation {
      accessScopes {
        handle
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query AccessScopeList {
    currentAppInstallation {
      accessScopes {
        handle
      }
    }
  }`,
});

Response

{
  "currentAppInstallation": {
    "accessScopes": [
      {
        "handle": "read_all_orders"
      },
      {
        "handle": "read_all_subscription_contracts"
      },
      {
        "handle": "read_analytics_overviews"
      },
      {
        "handle": "read_billing"
      },
      {
        "handle": "read_checkouts"
      },
      {
        "handle": "read_discovery"
      },
      {
        "handle": "read_discovery_synonym_groups"
      },
      {
        "handle": "read_payment_settings"
      },
      {
        "handle": "read_subscription_plans"
      },
      {
        "handle": "read_users"
      },
      {
        "handle": "read_customer_merge"
      },
      {
        "handle": "write_admin_shop_settings"
      },
      {
        "handle": "write_analytics_overviews"
      },
      {
        "handle": "write_apps"
      },
      {
        "handle": "write_brand"
      },
      {
        "handle": "write_brand_settings"
      },
      {
        "handle": "write_content"
      },
      {
        "handle": "write_customer_data_redaction_requests"
      },
      {
        "handle": "write_customer_payment_methods"
      },
      {
        "handle": "write_customers"
      },
      {
        "handle": "write_discounts"
      },
      {
        "handle": "write_discovery"
      },
      {
        "handle": "write_discovery_synonym_groups"
      },
      {
        "handle": "write_draft_orders"
      },
      {
        "handle": "write_files"
      },
      {
        "handle": "write_fulfillments"
      },
      {
        "handle": "write_gift_cards"
      },
      {
        "handle": "write_home"
      },
      {
        "handle": "write_inventory"
      },
      {
        "handle": "write_locations"
      },
      {
        "handle": "write_marketing_events"
      },
      {
        "handle": "write_media_processing"
      },
      {
        "handle": "write_merchant_managed_fulfillment_orders"
      },
      {
        "handle": "write_metaobjects"
      },
      {
        "handle": "write_metaobject_definitions"
      },
      {
        "handle": "write_notifications"
      },
      {
        "handle": "write_online_store"
      },
      {
        "handle": "write_online_store_pages"
      },
      {
        "handle": "write_online_store_navigation"
      },
      {
        "handle": "write_order_edits"
      },
      {
        "handle": "write_orders"
      },
      {
        "handle": "write_order_refunds"
      },
      {
        "handle": "write_payment_mandate"
      },
      {
        "handle": "write_price_rules"
      },
      {
        "handle": "write_products"
      },
      {
        "handle": "write_publications"
      },
      {
        "handle": "write_reports"
      },
      {
        "handle": "write_script_tags"
      },
      {
        "handle": "write_shipping"
      },
      {
        "handle": "write_themes"
      },
      {
        "handle": "write_third_party_fulfillment_orders"
      },
      {
        "handle": "write_customer_merge"
      },
      {
        "handle": "write_companies"
      },
      {
        "handle": "read_analytics"
      },
      {
        "handle": "read_admin_shop_settings"
      },
      {
        "handle": "read_apps"
      },
      {
        "handle": "read_brand"
      },
      {
        "handle": "read_brand_settings"
      },
      {
        "handle": "read_content"
      },
      {
        "handle": "read_customer_data_redaction_requests"
      },
      {
        "handle": "read_customer_payment_methods"
      },
      {
        "handle": "read_customers"
      },
      {
        "handle": "read_discounts"
      },
      {
        "handle": "read_draft_orders"
      },
      {
        "handle": "read_files"
      },
      {
        "handle": "read_fulfillments"
      },
      {
        "handle": "read_gift_cards"
      },
      {
        "handle": "read_home"
      },
      {
        "handle": "read_inventory"
      },
      {
        "handle": "read_locations"
      },
      {
        "handle": "read_marketing_events"
      },
      {
        "handle": "read_media_processing"
      },
      {
        "handle": "read_merchant_managed_fulfillment_orders"
      },
      {
        "handle": "read_metaobjects"
      },
      {
        "handle": "read_metaobject_definitions"
      },
      {
        "handle": "read_notifications"
      },
      {
        "handle": "read_online_store"
      },
      {
        "handle": "read_online_store_pages"
      },
      {
        "handle": "read_online_store_navigation"
      },
      {
        "handle": "read_order_edits"
      },
      {
        "handle": "read_orders"
      },
      {
        "handle": "read_payment_mandate"
      },
      {
        "handle": "read_price_rules"
      },
      {
        "handle": "read_products"
      },
      {
        "handle": "read_publications"
      },
      {
        "handle": "read_reports"
      },
      {
        "handle": "read_script_tags"
      },
      {
        "handle": "read_shipping"
      },
      {
        "handle": "read_themes"
      },
      {
        "handle": "read_third_party_fulfillment_orders"
      },
      {
        "handle": "read_companies"
      }
    ]
  }
}

Retrieves a list of application charges

Query

query {
  currentAppInstallation {
    oneTimePurchases(first: 10) {
      edges {
        node {
          createdAt
          id
          name
          price {
            amount
            currencyCode
          }
          status
          test
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { currentAppInstallation { oneTimePurchases(first: 10) { edges { node { createdAt id name price { amount currencyCode } status test } } } } }"
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    currentAppInstallation {
      oneTimePurchases(first: 10) {
        edges {
          node {
            createdAt
            id
            name
            price {
              amount
              currencyCode
            }
            status
            test
          }
        }
      }
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query {
    currentAppInstallation {
      oneTimePurchases(first: 10) {
        edges {
          node {
            createdAt
            id
            name
            price {
              amount
              currencyCode
            }
            status
            test
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    currentAppInstallation {
      oneTimePurchases(first: 10) {
        edges {
          node {
            createdAt
            id
            name
            price {
              amount
              currencyCode
            }
            status
            test
          }
        }
      }
    }
  }`,
});

Response

{
  "currentAppInstallation": {
    "oneTimePurchases": {
      "edges": []
    }
  }
}

Retrieves a list of recurring application charges

Query

query GetRecurringApplicationCharges {
  currentAppInstallation {
    activeSubscriptions {
      id
      name
      status
      lineItems {
        id
        plan {
          pricingDetails {
            __typename
          }
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query GetRecurringApplicationCharges { currentAppInstallation { activeSubscriptions { id name status lineItems { id plan { pricingDetails { __typename } } } } } }"
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query GetRecurringApplicationCharges {
    currentAppInstallation {
      activeSubscriptions {
        id
        name
        status
        lineItems {
          id
          plan {
            pricingDetails {
              __typename
            }
          }
        }
      }
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query GetRecurringApplicationCharges {
    currentAppInstallation {
      activeSubscriptions {
        id
        name
        status
        lineItems {
          id
          plan {
            pricingDetails {
              __typename
            }
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query GetRecurringApplicationCharges {
    currentAppInstallation {
      activeSubscriptions {
        id
        name
        status
        lineItems {
          id
          plan {
            pricingDetails {
              __typename
            }
          }
        }
      }
    }
  }`,
});

Response

{
  "currentAppInstallation": {
    "activeSubscriptions": []
  }
}

Examples

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

query AccessScopeList {

currentAppInstallation {

accessScopes {

handle

}

}`,

);

const json = await response.json();

return json.data;

}

GQL

query AccessScopeList {
  currentAppInstallation {
    accessScopes {
      handle
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query AccessScopeList { currentAppInstallation { accessScopes { handle } } }"
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query AccessScopeList {
    currentAppInstallation {
      accessScopes {
        handle
      }
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query AccessScopeList {
    currentAppInstallation {
      accessScopes {
        handle
      }
    }
  }`,
});

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query AccessScopeList {
    currentAppInstallation {
      accessScopes {
        handle
      }
    }
  }
QUERY

response = client.query(query: query)

Response

JSON

{

"currentAppInstallation": {

"accessScopes": [

{

"handle": "read_all_orders"

{

"handle": "read_all_subscription_contracts"

{

"handle": "read_analytics_overviews"

{

"handle": "read_billing"

{

"handle": "read_checkouts"

{

"handle": "read_discovery"

{

"handle": "read_discovery_synonym_groups"

{

"handle": "read_payment_settings"

{

"handle": "read_subscription_plans"

{

"handle": "read_users"

{

"handle": "read_customer_merge"