Shopify GraphQL Admin API

https://shopify.dev/docs/api/admin-graphql/2026-01
Admin
Shopify GraphQL Admin API is a modern API that lets developers build apps and integrations to extend...
Tokens:5,622,845
Snippets:32,072
Trust Score:9.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Ruby: Get app associated with installation

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this Ruby example to query the app ID for an installation. It creates a session and client, then executes the GraphQL query.

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

--------------------------------

### Get launchUrl using Ruby

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this Ruby example to query the launchUrl field of an appInstallation. It creates a Shopify API session and client, then sends a GraphQL query. The response contains the launchUrl for the specified app installation ID.

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

--------------------------------

### Get launchUrl using Node.js

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this Node.js example to query the launchUrl field of an appInstallation. It uses the Shopify API client to send a GraphQL query. The response contains the launchUrl for the specified app installation ID.

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

--------------------------------

### Response: Get app associated with installation

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Example JSON response for the app ID query. It shows the structure with the appInstallation object containing the app ID.

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

--------------------------------

### Node.js: Get app associated with installation

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this Node.js example to query the app ID for an installation using the Shopify GraphQL client. It sends the query and returns the data.

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

--------------------------------

### Ruby client for non-existent product

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/tagsAdd

Ruby client example for the non-existent product case. Uses the same session and client setup with the invalid product ID.

```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
  mutation addTags($id: ID!, $tags: [String!]!) {
    tagsAdd(id: $id, tags: $tags) {
      node {
        id
      }
      userErrors {
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Product/12345",
  "tags": "one, two, three"
}

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

--------------------------------

### Ruby: Create BXGY automatic discount

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/discountAutomaticBxgyCreate

Use this Ruby example to create a buy X get Y automatic discount. It constructs a Shopify API session, creates a GraphQL admin client, and sends the mutation with the required variables. The example sets up a customer buys one product and gets another product at 100% off, with a uses per order limit of 1.

```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
  mutation CreateBxgyDiscount($automaticBxgyDiscount: DiscountAutomaticBxgyInput!) {
    discountAutomaticBxgyCreate(automaticBxgyDiscount: $automaticBxgyDiscount) {
      automaticDiscountNode {
        id
        automaticDiscount {
          ... on DiscountAutomaticBxgy {
            title
            startsAt
            endsAt
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "automaticBxgyDiscount": {
    "title": "Buy first product, get second product free",
    "startsAt": "2025-01-01T00:00:00Z",
    "endsAt": "2025-12-31T23:59:59Z",
    "customerBuys": {
      "items": {
        "products": {
          "productsToAdd": [
            "gid://shopify/Product/108828309"
          ]
        }
      },
      "value": {
        "quantity": "1"
      }
    },
    "customerGets": {
      "items": {
        "products": {
          "productsToAdd": [
            "gid://shopify/Product/20995642"
          ]
        }
      },
      "value": {
        "discountOnQuantity": {
          "quantity": "1",
          "effect": {
            "percentage": 1
          }
        }
      }
    },
    "usesPerOrderLimit": "1"
  }
}

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

--------------------------------

### Get launchUrl using Direct API Access

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this JavaScript example to query the launchUrl field of an appInstallation via direct API access. It sends a POST request to the GraphQL endpoint and logs the response data. The response contains the launchUrl for the specified app installation ID.

```javascript
const response = await fetch('shopify:admin/api/2026-01/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query {
        appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
          launchUrl
        }
      }
    `,
  }),
});

const { data } = await response.json();
console.log(data);
```

--------------------------------

### Ruby - themeFilesCopy

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/themeFilesCopy

Ruby example using the Shopify API client to run the themeFilesCopy mutation. Includes session setup and query execution.

```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
  mutation ThemeFilesCopy($files: [ThemeFilesCopyFileInput!]!, $themeId: ID!) {
    themeFilesCopy(files: $files, themeId: $themeId) {
      copiedThemeFiles {
        filename
      }
      userErrors {
        code
        field
        filename
        message
      }
    }
  }
QUERY

variables = {
  "themeId": "gid://shopify/OnlineStoreTheme/529529152",
  "files": [
    {
      "dstFilename": "templates/index.alt.liquid",
      "srcFilename": "templates/index.liquid"
    }
  ]
}

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

--------------------------------

### Get a metafield attached to an app installation - Response

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Example JSON response for the AppInstallationMetafield query.

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

--------------------------------

### Shopify CLI Command for GetAppInstallationCredits

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Shows how to execute the query using the Shopify CLI with the --query and --variables flags.

```bash
shopify app execute \
--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"
}'
```

--------------------------------

### Get a metafield attached to an app installation - Node.js

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Node.js example using shopify.clients.Graphql to run the AppInstallationMetafield query.

```javascript
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 Example for themeCreate

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/themeCreate

A Ruby example using the Shopify API gem to create a theme, with a query and variables.

```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
  mutation themeCreate($source: URL!, $name: String!) {
    themeCreate(source: $source, name: $name) {
      theme {
        name
        role
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "source": "http://www.example.com/dawn.zip",
  "name": "Dawn"
}

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

--------------------------------

### Get refund duties - Ruby client

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/refund

Ruby client setup and query execution for the refund duties example.

```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 refund($input: ID!) {
    refund(id: $input) {
      duties {
        originalDuty {
          countryCodeOfOrigin
        }
        amountSet {
          shopMoney {
            amount
          }
        }
      }
    }
  }
QUERY

variables = {
  "input": "gid://shopify/Refund/850600470"
}

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

--------------------------------

### Direct API access for appInstallation query

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this example to query access scopes for an app installation via a direct fetch call to the GraphQL endpoint. It sends a POST request with the query in the body and logs the response data. The query requests the accessScopes field with handle and description.

```javascript
const response = await fetch('shopify:admin/api/2026-01/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query {
        appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
          accessScopes {
            handle
            description
          }
        }
      }
    `,
  }),
});

const { data } = await response.json();
console.log(data);
```

--------------------------------

### Get a metafield attached to an app installation - Ruby

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Ruby example using ShopifyAPI::Clients::Graphql::Admin to run the AppInstallationMetafield query.

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

--------------------------------

### Ruby client for productReorderMedia

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/productReorderMedia

Ruby example using ShopifyAPI::Clients::Graphql::Admin to execute the mutation. Requires a session with shop and access token.

```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
  mutation productReorderMedia($id: ID!, $moves: [MoveInput!]!) {
    productReorderMedia(id: $id, moves: $moves) {
      job {
        id
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Product/108828309",
  "moves": [
    {
      "id": "gid://shopify/MediaImage/183532652",
      "newPosition": "2"
    },
    {
      "id": "gid://shopify/MediaImage/731367280",
      "newPosition": "3"
    }
  ]
}

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

--------------------------------

### Receive a single Blog Shopify CLI

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/blog

Example command using the Shopify CLI.

```bash
shopify app execute \
--query \
'query BlogShow($id: ID!) {
  blog(id: $id) {
    id
    title
    handle
  }
}' \
--variables \
'{
  "id": "gid://shopify/Blog/397675442"
}'
```

--------------------------------

### Node.js: Get active subscriptions

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this Node.js example to query active subscriptions for an app installation using the Shopify GraphQL client. It sends the query and returns the data.

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

--------------------------------

### Ruby Client for GetAppInstallationCredits

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Uses the Shopify Ruby gem to create a session and client, then executes the query with the provided variables.

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

--------------------------------

### Ruby client for appInstallation query

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this Ruby example to query access scopes for an app installation using the Shopify API Ruby client. It creates a session, initializes a GraphQL admin client, and sends the query. The query requests the accessScopes field with handle and description.

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

--------------------------------

### Get total refunded amount - Ruby

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/refund

Ruby example using the Shopify Admin GraphQL client to query the total refunded amount. Requires a session and client setup.

```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 refund($input: ID!) {
    refund(id: $input) {
      totalRefundedSet {
        shopMoney {
          amount
          currencyCode
        }
      }
    }
  }
QUERY

variables = {
  "input": "gid://shopify/Refund/196417871"
}

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

--------------------------------

### Response for currentAppInstallation query

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/currentAppInstallation

Example response showing an empty activeSubscriptions array when the app has no active subscriptions.

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

--------------------------------

### Ruby: Get active subscriptions

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this Ruby example to query active subscriptions for an app installation using the Shopify API client. It creates a session and client, then executes the GraphQL query.

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

--------------------------------

### Direct API Access: fetch to GraphQL endpoint

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/menuUpdate

Starts a direct API access example using fetch to the Shopify Admin GraphQL endpoint. The code is incomplete in the source, showing only the beginning of the request setup.

```javascript
const response = await fetch('shopify:admin/api/2026-01/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
```

--------------------------------

### GraphQL Query: Get app associated with installation

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

This GraphQL query retrieves the application associated with the installation, returning the associated ID. It is used to get the app ID for a given installation.

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

--------------------------------

### Initialize Shopify Admin GraphQL client in Ruby

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/draftOrderInvoiceSend

Ruby setup for the Shopify Admin GraphQL client. Creates a session with your store and access token, then initializes the client.

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

--------------------------------

### Node.js client for appInstallation query

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this Node.js example to query access scopes for an app installation using the Shopify Node.js client. It creates a GraphQL client with the session and sends the query. The query requests the accessScopes field with handle and description.

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

--------------------------------

### Direct API Access: Get app associated with installation

Source: https://shopify.dev/docs/api/admin-graphql/2026-01/queries/appInstallation

Use this direct API access example to fetch the app ID by sending a POST request to the GraphQL endpoint. It uses fetch and logs the response data.

```javascript
const response = await fetch('shopify:admin/api/2026-01/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query {
        appInstallation(id: "gid://shopify/AppInstallation/1002334195") {
          app {
            id
          }
        }
      }
    `,
  }),
});

const { data } = await response.json();
console.log(data);
```
Tokens:
Raw