Choose a version:

appInstallation

query

Lookup an AppInstallation by ID or return the AppInstallation for the currently authenticated App.

Arguments

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

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to AppInstallationAppInstallation •AppInstallation: Represents an installed application on a shop.

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/unstable/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"
  }
}'

Remix

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 data = await response.json();

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/unstable/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"
  }
}'

Remix

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 data = await response.json();

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/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { appInstallation(id: \"gid://shopify/AppInstallation/1002334195\") { launchUrl } }"
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  query {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      launchUrl
    }
  }`,
);

const data = await response.json();

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/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { appInstallation(id: \"gid://shopify/AppInstallation/688276949\") { uninstallUrl } }"
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  query {
    appInstallation(id: "gid://shopify/AppInstallation/688276949") {
      uninstallUrl
    }
  }`,
);

const data = await response.json();

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/unstable/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 } } }"
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  query {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      accessScopes {
        handle
        description
      }
    }
  }`,
);

const data = await response.json();

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/unstable/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 } } }"
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  query {
    appInstallation(id: "gid://shopify/AppInstallation/881878037") {
      activeSubscriptions {
        id
      }
    }
  }`,
);

const data = await response.json();

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/unstable/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 } } }"
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  query {
    appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
      app {
        id
      }
    }
  }`,
);

const data = await response.json();

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/unstable/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"
  }
}'

Remix

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 data = await response.json();

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

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 data = await response.json();

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

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/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"
  }
}'

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 data = await response.json();

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"
    },
  },
});

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="

}