Choose a version:

appInstallation

query

Retrieves an AppInstallation by ID. If no ID is provided, returns the installation for the currently authenticated App. The query provides essential data for validating installation state and managing app functionality within a store.

Use this query to access installation details including granted AccessScope objects, active AppSubscription objects, AppCredit objects, AppPurchaseOneTime objects, and app-specific metadata.

Learn more about app installation.

Anchor to Arguments

Arguments

Anchor to idid •ID: ID used to lookup AppInstallation.

Was this section helpful?

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 metafield attached to an app installation

Description

Get the metafield value identified by `secret_keys.api_key` on a specific app installation.

Query

query AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
  appInstallation(id: $ownerId) {
    apiKey: metafield(namespace: $namespace, key: $key) {
      value
    }
  }
}

Variables

{
  "namespace": "secret_keys",
  "key": "api_key",
  "ownerId": "gid://shopify/AppInstallation/1002334195"
}

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 AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) { appInstallation(id: $ownerId) { apiKey: metafield(namespace: $namespace, key: $key) { value } } }",
 "variables": {
    "namespace": "secret_keys",
    "key": "api_key",
    "ownerId": "gid://shopify/AppInstallation/1002334195"
  }
}'

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 AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
    appInstallation(id: $ownerId) {
      apiKey: metafield(namespace: $namespace, key: $key) {
        value
      }
    }
  }`,
  {
    variables: {
        "namespace": "secret_keys",
        "key": "api_key",
        "ownerId": "gid://shopify/AppInstallation/1002334195"
    },
  },
  );
  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 AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
    appInstallation(id: $ownerId) {
      apiKey: metafield(namespace: $namespace, key: $key) {
        value
      }
    }
  }
QUERY

variables = {
  "namespace": "secret_keys",
  "key": "api_key",
  "ownerId": "gid://shopify/AppInstallation/1002334195"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
      appInstallation(id: $ownerId) {
        apiKey: metafield(namespace: $namespace, key: $key) {
          value
        }
      }
    }`,
    "variables": {
        "namespace": "secret_keys",
        "key": "api_key",
        "ownerId": "gid://shopify/AppInstallation/1002334195"
    },
  },
});

Response

{
  "appInstallation": {
    "apiKey": {
      "value": "aSBhbSBhIHNlY3JldCBrZXk="
    }
  }
}

Get metafields attached to an app installation

Description

Get a page of metafields attached to a specific app installation.

Query

query AppInstallationMetafields($ownerId: ID!) {
  appInstallation(id: $ownerId) {
    metafields(first: 3) {
      edges {
        node {
          namespace
          key
          value
        }
      }
    }
  }
}

Variables

{
  "ownerId": "gid://shopify/AppInstallation/1002334195"
}

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 AppInstallationMetafields($ownerId: ID!) { appInstallation(id: $ownerId) { metafields(first: 3) { edges { node { namespace key value } } } } }",
 "variables": {
    "ownerId": "gid://shopify/AppInstallation/1002334195"
  }
}'

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 AppInstallationMetafields($ownerId: ID!) {
    appInstallation(id: $ownerId) {
      metafields(first: 3) {
        edges {
          node {
            namespace
            key
            value
          }
        }
      }
    }
  }`,
  {
    variables: {
        "ownerId": "gid://shopify/AppInstallation/1002334195"
    },
  },
  );
  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 AppInstallationMetafields($ownerId: ID!) {
    appInstallation(id: $ownerId) {
      metafields(first: 3) {
        edges {
          node {
            namespace
            key
            value
          }
        }
      }
    }
  }
QUERY

variables = {
  "ownerId": "gid://shopify/AppInstallation/1002334195"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query AppInstallationMetafields($ownerId: ID!) {
      appInstallation(id: $ownerId) {
        metafields(first: 3) {
          edges {
            node {
              namespace
              key
              value
            }
          }
        }
      }
    }`,
    "variables": {
        "ownerId": "gid://shopify/AppInstallation/1002334195"
    },
  },
});

Response

{
  "appInstallation": {
    "metafields": {
      "edges": [
        {
          "node": {
            "namespace": "secret_keys",
            "key": "api_key",
            "value": "aSBhbSBhIHNlY3JldCBrZXk="
          }
        }
      ]
    }
  }
}

Get the URL used to launch the application

Description

The following query retrieves the launchUrl associated with the appInstallation.

Query

query {
  appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
    launchUrl
  }
}

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 { appInstallation(id: \"gid://shopify/AppInstallation/1002334195\") { launchUrl } }"
}'

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 {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      launchUrl
    }
  }`,
  );
  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 {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      launchUrl
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      launchUrl
    }
  }`,
});

Response

{
  "appInstallation": {
    "launchUrl": "https://snowdevil.myshopify.com/admin/api_permissions/1002334195/redirect"
  }
}

Get the URL used to uninstall the application

Description

The following query retrieves the uninstallUrl associated with the appInstallation.

Query

query {
  appInstallation(id: "gid://shopify/AppInstallation/688276949") {
    uninstallUrl
  }
}

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 { appInstallation(id: \"gid://shopify/AppInstallation/688276949\") { uninstallUrl } }"
}'

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 {
    appInstallation(id: "gid://shopify/AppInstallation/688276949") {
      uninstallUrl
    }
  }`,
  );
  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 {
    appInstallation(id: "gid://shopify/AppInstallation/688276949") {
      uninstallUrl
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    appInstallation(id: "gid://shopify/AppInstallation/688276949") {
      uninstallUrl
    }
  }`,
});

Response

{
  "appInstallation": {
    "uninstallUrl": null
  }
}

Get the access scopes associated with the app installation

Description

The following query returns all the access scopes that were granted to the application during installation.

Query

query {
  appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
    accessScopes {
      handle
      description
    }
  }
}

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 { appInstallation(id: \"gid://shopify/AppInstallation/1002334195\") { accessScopes { handle description } } }"
}'

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 {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      accessScopes {
        handle
        description
      }
    }
  }`,
  );
  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 {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      accessScopes {
        handle
        description
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      accessScopes {
        handle
        description
      }
    }
  }`,
});

Response

{
  "appInstallation": {
    "accessScopes": [
      {
        "handle": "write_content",
        "description": "Modify store content like articles, blogs, comments, pages, and redirects"
      },
      {
        "handle": "write_themes",
        "description": "Modify theme templates and theme assets"
      },
      {
        "handle": "write_products",
        "description": "Modify products, variants, and collections"
      },
      {
        "handle": "write_customers",
        "description": "Modify customer details and customer groups"
      },
      {
        "handle": "write_orders",
        "description": "Modify orders, transactions, and fulfillments"
      },
      {
        "handle": "write_script_tags",
        "description": "Modify script tags in your store's theme template files"
      },
      {
        "handle": "write_shipping",
        "description": "Modify shipping rates, countries, and provinces"
      },
      {
        "handle": "read_content",
        "description": "Read store content like articles, blogs, comments, pages, and redirects"
      },
      {
        "handle": "read_themes",
        "description": "Read theme templates and theme assets"
      },
      {
        "handle": "read_products",
        "description": "Read products, variants, and collections"
      },
      {
        "handle": "read_customers",
        "description": "Read customer details and customer groups"
      },
      {
        "handle": "read_orders",
        "description": "Read orders, transactions, and fulfillments"
      },
      {
        "handle": "read_script_tags",
        "description": "Read script tags in your store's theme template files"
      },
      {
        "handle": "read_shipping",
        "description": "Read shipping rates, countries, and provinces"
      }
    ]
  }
}

Get the active subscriptions for the app installation

Description

The following query returns the IDs of the active subscriptions billed by the application. Returns an "access denied" error if the user is not allowed to approve application charges.

Query

query {
  appInstallation(id: "gid://shopify/AppInstallation/881878037") {
    activeSubscriptions {
      id
    }
  }
}

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 { appInstallation(id: \"gid://shopify/AppInstallation/881878037\") { activeSubscriptions { id } } }"
}'

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 {
    appInstallation(id: "gid://shopify/AppInstallation/881878037") {
      activeSubscriptions {
        id
      }
    }
  }`,
  );
  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 {
    appInstallation(id: "gid://shopify/AppInstallation/881878037") {
      activeSubscriptions {
        id
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    appInstallation(id: "gid://shopify/AppInstallation/881878037") {
      activeSubscriptions {
        id
      }
    }
  }`,
});

Response

{
  "appInstallation": {
    "activeSubscriptions": [
      {
        "id": "gid://shopify/AppSubscription/1029266946"
      }
    ]
  }
}

Get the app associated with the installation

Description

The following query retrieves the application associated with the installation, returning the associated ID.

Query

query {
  appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
    app {
      id
    }
  }
}

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 { appInstallation(id: \"gid://shopify/AppInstallation/1002334195\") { app { id } } }"
}'

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 {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      app {
        id
      }
    }
  }`,
  );
  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 {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      app {
        id
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      app {
        id
      }
    }
  }`,
});

Response

{
  "appInstallation": {
    "app": {
      "id": "gid://shopify/App/1002334195"
    }
  }
}

Retrieves all application credits

Query

query GetAppInstallationCredits($appInstallationId: ID!) {
  appInstallation(id: $appInstallationId) {
    credits(first: 10) {
      edges {
        node {
          amount {
            amount
            currencyCode
          }
          createdAt
          description
          id
        }
      }
    }
  }
}

Variables

{
  "appInstallationId": "gid://shopify/AppInstallation/236444539"
}

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 GetAppInstallationCredits($appInstallationId: ID!) { appInstallation(id: $appInstallationId) { credits(first: 10) { edges { node { amount { amount currencyCode } createdAt description id } } } } }",
 "variables": {
    "appInstallationId": "gid://shopify/AppInstallation/236444539"
  }
}'

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 GetAppInstallationCredits($appInstallationId: ID!) {
    appInstallation(id: $appInstallationId) {
      credits(first: 10) {
        edges {
          node {
            amount {
              amount
              currencyCode
            }
            createdAt
            description
            id
          }
        }
      }
    }
  }`,
  {
    variables: {
        "appInstallationId": "gid://shopify/AppInstallation/236444539"
    },
  },
  );
  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 GetAppInstallationCredits($appInstallationId: ID!) {
    appInstallation(id: $appInstallationId) {
      credits(first: 10) {
        edges {
          node {
            amount {
              amount
              currencyCode
            }
            createdAt
            description
            id
          }
        }
      }
    }
  }
QUERY

variables = {
  "appInstallationId": "gid://shopify/AppInstallation/236444539"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query GetAppInstallationCredits($appInstallationId: ID!) {
      appInstallation(id: $appInstallationId) {
        credits(first: 10) {
          edges {
            node {
              amount {
                amount
                currencyCode
              }
              createdAt
              description
              id
            }
          }
        }
      }
    }`,
    "variables": {
        "appInstallationId": "gid://shopify/AppInstallation/236444539"
    },
  },
});

Response

{
  "appInstallation": {
    "credits": {
      "edges": []
    }
  }
}

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 AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {

appInstallation(id: $ownerId) {

apiKey: metafield(namespace: $namespace, key: $key) {

value

}

}`,

{

variables: {

"namespace": "secret_keys",

"key": "api_key",

"ownerId": "gid://shopify/AppInstallation/1002334195"

);

const json = await response.json();

return json.data;

}

GQL

query AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
  appInstallation(id: $ownerId) {
    apiKey: metafield(namespace: $namespace, key: $key) {
      value
    }
  }
}

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 AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) { appInstallation(id: $ownerId) { apiKey: metafield(namespace: $namespace, key: $key) { value } } }",
 "variables": {
    "namespace": "secret_keys",
    "key": "api_key",
    "ownerId": "gid://shopify/AppInstallation/1002334195"
  }
}'

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 AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
    appInstallation(id: $ownerId) {
      apiKey: metafield(namespace: $namespace, key: $key) {
        value
      }
    }
  }`,
  {
    variables: {
        "namespace": "secret_keys",
        "key": "api_key",
        "ownerId": "gid://shopify/AppInstallation/1002334195"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
      appInstallation(id: $ownerId) {
        apiKey: metafield(namespace: $namespace, key: $key) {
          value
        }
      }
    }`,
    "variables": {
        "namespace": "secret_keys",
        "key": "api_key",
        "ownerId": "gid://shopify/AppInstallation/1002334195"
    },
  },
});

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 AppInstallationMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
    appInstallation(id: $ownerId) {
      apiKey: metafield(namespace: $namespace, key: $key) {
        value
      }
    }
  }
QUERY

variables = {
  "namespace": "secret_keys",
  "key": "api_key",
  "ownerId": "gid://shopify/AppInstallation/1002334195"
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"namespace": "secret_keys",

"key": "api_key",

"ownerId": "gid://shopify/AppInstallation/1002334195"

}

Response

JSON

{

"appInstallation": {

"apiKey": {

"value": "aSBhbSBhIHNlY3JldCBrZXk="

}