Choose a version:

rollout

query

A rollout on a shop.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the rollout.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to RolloutRollout

•Rollout

A rollout on a shop. Merchants use rollouts to run sales events, permanent launches, and A/B tests by serving treatments to a configured share of buyers.

Show fields

Anchor to archivedAtarchivedAt

•DateTime

The date and time at which the rollout was archived.

Anchor to concludedAtconcludedAt

•DateTime

The actual conclusion date and time of the rollout for public API requests. Use schedule.concludeAt for the planned conclusion date.

Anchor to createdAtcreatedAt

•DateTime!

non-null

The date and time at which the rollout was created.

Anchor to effectiveTrafficAllocationeffectiveTrafficAllocation

•Float!

non-null

The effective percentage of total traffic this rollout receives for new buyer assignments, accounting for mutex group constraints with other active rollouts.

Anchor to idid

•ID!

non-null

The ID of the rollout.

Anchor to namename

•String!

non-null

The name of the rollout.

Anchor to scheduleschedule

•RolloutSchedule

The rollout's planned activation and conclusion dates. Returns null when neither date is set.

Show fields

Anchor to startedAtstartedAt

•DateTime

The actual start date and time of the rollout for public API requests. Use schedule.activateAt for the planned activation date.

Anchor to statusstatus

•RolloutStatus!

non-null

The status of the rollout.

Show enum values

Anchor to trafficAllocationtrafficAllocation

•Int!

non-null

The percentage of buyer traffic that the rollout is configured to receive, as an integer from 0 to 100. This is the configured allocation before other active rollouts on the same resources are taken into account, so it isn't the share of buyers that a treatment reaches.

Anchor to treatmentstreatments

•[RolloutTreatment!]!

non-null

The treatments of the rollout. Control treatments are included even when they have no changes.

Show fields

Anchor to updatedAtupdatedAt

•DateTime!

non-null

The date and time at which the rollout was last edited. This timestamp doesn't necessarily change when another rollout changes this rollout's effective traffic allocation.

Was this section helpful?

Examples

Read change identities without discount access

Description

Read only `id` and `__typename` with `read_rollouts` when your app lacks `read_discounts`. The IDs identify changes, not protected discount resources. Omit the `discount` selection: requesting it without access returns field-level `ACCESS_DENIED` errors and null payloads. Missing `read_rollouts` denies the rollout read itself. Track `changes.pageInfo` separately for each treatment ID. An empty baseline has no changes to continue. When a treatment has another page, pass its ID and end cursor to `node(id:)` and select `RolloutTreatment.changes`. Keep the same query filter and `reverse` value (`false` here); never share a changes cursor with another treatment.

Query

query ReadRolloutChangeIdentities($id: ID!) {
  rollout(id: $id) {
    id
    name
    treatments {
      id
      changes(first: 10, reverse: false) {
        nodes {
          id
          __typename
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}

Variables

{
  "id": "gid://shopify/Rollout/532060658"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query ReadRolloutChangeIdentities($id: ID!) { rollout(id: $id) { id name treatments { id changes(first: 10, reverse: false) { nodes { id __typename } pageInfo { hasNextPage endCursor } } } } }",
 "variables": {
    "id": "gid://shopify/Rollout/532060658"
  }
}'

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 ReadRolloutChangeIdentities($id: ID!) {
    rollout(id: $id) {
      id
      name
      treatments {
        id
        changes(first: 10, reverse: false) {
          nodes {
            id
            __typename
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Rollout/532060658"
    },
  },
  );
  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 ReadRolloutChangeIdentities($id: ID!) {
    rollout(id: $id) {
      id
      name
      treatments {
        id
        changes(first: 10, reverse: false) {
          nodes {
            id
            __typename
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Rollout/532060658"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query ReadRolloutChangeIdentities($id: ID!) {
      rollout(id: $id) {
        id
        name
        treatments {
          id
          changes(first: 10, reverse: false) {
            nodes {
              id
              __typename
            }
            pageInfo {
              hasNextPage
              endCursor
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Rollout/532060658"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query ReadRolloutChangeIdentities($id: ID!) {
  rollout(id: $id) {
    id
    name
    treatments {
      id
      changes(first: 10, reverse: false) {
        nodes {
          id
          __typename
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Rollout/532060658"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query ReadRolloutChangeIdentities($id: ID!) {
        rollout(id: $id) {
          id
          name
          treatments {
            id
            changes(first: 10, reverse: false) {
              nodes {
                id
                __typename
              }
              pageInfo {
                hasNextPage
                endCursor
              }
            }
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Rollout/532060658"
    },
  }),
});

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

Response

{
  "rollout": {
    "id": "gid://shopify/Rollout/532060658",
    "name": "Black Friday offer changeover",
    "treatments": [
      {
        "id": "gid://shopify/RolloutTreatment/522314081",
        "changes": {
          "nodes": [
            {
              "id": "gid://shopify/RolloutDiscountActivateChange/19562284969ac8973c308a5159bf122bb6cc5966282d620bfbf81e7029f1e686",
              "__typename": "RolloutDiscountActivateChange"
            },
            {
              "id": "gid://shopify/RolloutDiscountExpireChange/c2f0dd9c068a6dba4866e563632bc485070d427fd72568094e761b30fa639467",
              "__typename": "RolloutDiscountExpireChange"
            }
          ],
          "pageInfo": {
            "hasNextPage": false,
            "endCursor": "WzEsIjQ4NDYzOWJkYmU5NTExNjA4NDJiYTNhNzJiYjEyYWE4MjhjZmJjNmFiNjU4YTI0YWYwZTZmZTUxN2JhMzM4M2EiLCIyMDI2LTExLTAxVDAwOjAwOjAwLjAwMDAwMDAwMFoiLDEsImMyZjBkZDljMDY4YTZkYmE0ODY2ZTU2MzYzMmJjNDg1MDcwZDQyN2ZkNzI1NjgwOTRlNzYxYjMwZmE2Mzk0NjciXQ"
          }
        }
      },
      {
        "id": "gid://shopify/RolloutTreatment/755492298",
        "changes": {
          "nodes": [],
          "pageInfo": {
            "hasNextPage": false,
            "endCursor": null
          }
        }
      }
    ]
  }
}

Read retained changes after a discount is deleted

Description

Read a concluded rollout after an affected discount is deleted. The change keeps its `id` and `__typename`, but its `discount` field is `null`. Don't discard the change or treat its opaque ID as a readable Discount ID. This root lookup requires `read_rollouts`; reading surviving discount payloads also requires `read_discounts`.

Query

query ReadRolloutChanges($id: ID!, $first: Int!) {
  rollout(id: $id) {
    id
    name
    status
    treatments {
      id
      changes(first: $first) {
        nodes {
          id
          __typename
          ... on RolloutDiscountChange {
            discount {
              id
            }
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}

Variables

{
  "id": "gid://shopify/Rollout/532060658",
  "first": 10
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query ReadRolloutChanges($id: ID!, $first: Int!) { rollout(id: $id) { id name status treatments { id changes(first: $first) { nodes { id __typename ... on RolloutDiscountChange { discount { id } } } pageInfo { hasNextPage endCursor } } } } }",
 "variables": {
    "id": "gid://shopify/Rollout/532060658",
    "first": 10
  }
}'

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 ReadRolloutChanges($id: ID!, $first: Int!) {
    rollout(id: $id) {
      id
      name
      status
      treatments {
        id
        changes(first: $first) {
          nodes {
            id
            __typename
            ... on RolloutDiscountChange {
              discount {
                id
              }
            }
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Rollout/532060658",
        "first": 10
    },
  },
  );
  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 ReadRolloutChanges($id: ID!, $first: Int!) {
    rollout(id: $id) {
      id
      name
      status
      treatments {
        id
        changes(first: $first) {
          nodes {
            id
            __typename
            ... on RolloutDiscountChange {
              discount {
                id
              }
            }
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Rollout/532060658",
  "first": 10
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query ReadRolloutChanges($id: ID!, $first: Int!) {
      rollout(id: $id) {
        id
        name
        status
        treatments {
          id
          changes(first: $first) {
            nodes {
              id
              __typename
              ... on RolloutDiscountChange {
                discount {
                  id
                }
              }
            }
            pageInfo {
              hasNextPage
              endCursor
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Rollout/532060658",
        "first": 10
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query ReadRolloutChanges($id: ID!, $first: Int!) {
  rollout(id: $id) {
    id
    name
    status
    treatments {
      id
      changes(first: $first) {
        nodes {
          id
          __typename
          ... on RolloutDiscountChange {
            discount {
              id
            }
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Rollout/532060658",
  "first": 10
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query ReadRolloutChanges($id: ID!, $first: Int!) {
        rollout(id: $id) {
          id
          name
          status
          treatments {
            id
            changes(first: $first) {
              nodes {
                id
                __typename
                ... on RolloutDiscountChange {
                  discount {
                    id
                  }
                }
              }
              pageInfo {
                hasNextPage
                endCursor
              }
            }
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Rollout/532060658",
        "first": 10
    },
  }),
});

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

Response

{
  "rollout": {
    "id": "gid://shopify/Rollout/532060658",
    "name": "Black Friday offer changeover",
    "status": "CONCLUDED",
    "treatments": [
      {
        "id": "gid://shopify/RolloutTreatment/522314081",
        "changes": {
          "nodes": [
            {
              "id": "gid://shopify/RolloutDiscountActivateChange/19562284969ac8973c308a5159bf122bb6cc5966282d620bfbf81e7029f1e686",
              "__typename": "RolloutDiscountActivateChange",
              "discount": {
                "id": "gid://shopify/DiscountAutomaticNode/299501151"
              }
            },
            {
              "id": "gid://shopify/RolloutDiscountExpireChange/c2f0dd9c068a6dba4866e563632bc485070d427fd72568094e761b30fa639467",
              "__typename": "RolloutDiscountExpireChange",
              "discount": null
            }
          ],
          "pageInfo": {
            "hasNextPage": false,
            "endCursor": "WzEsIjQ4NDYzOWJkYmU5NTExNjA4NDJiYTNhNzJiYjEyYWE4MjhjZmJjNmFiNjU4YTI0YWYwZTZmZTUxN2JhMzM4M2EiLCIyMDI2LTExLTAxVDAwOjAwOjAwLjAwMDAwMDAwMFoiLDEsImMyZjBkZDljMDY4YTZkYmE0ODY2ZTU2MzYzMmJjNDg1MDcwZDQyN2ZkNzI1NjgwOTRlNzYxYjMwZmE2Mzk0NjciXQ"
          }
        }
      },
      {
        "id": "gid://shopify/RolloutTreatment/755492298",
        "changes": {
          "nodes": [],
          "pageInfo": {
            "hasNextPage": false,
            "endCursor": null
          }
        }
      }
    ]
  }
}

Retrieve the planned schedule of a rollout

Description

Retrieve the stored planned activation and optional conclusion dates, not actual lifecycle timestamps. The schedule remains the planned dates for concluded and archived rollouts, and is null when neither date is set.

Query

query RolloutSchedule($id: ID!) {
  rollout(id: $id) {
    id
    schedule {
      activateAt
      concludeAt
    }
  }
}

Variables

{
  "id": "gid://shopify/Rollout/179220554"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query RolloutSchedule($id: ID!) { rollout(id: $id) { id schedule { activateAt concludeAt } } }",
 "variables": {
    "id": "gid://shopify/Rollout/179220554"
  }
}'

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 RolloutSchedule($id: ID!) {
    rollout(id: $id) {
      id
      schedule {
        activateAt
        concludeAt
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Rollout/179220554"
    },
  },
  );
  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 RolloutSchedule($id: ID!) {
    rollout(id: $id) {
      id
      schedule {
        activateAt
        concludeAt
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Rollout/179220554"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query RolloutSchedule($id: ID!) {
      rollout(id: $id) {
        id
        schedule {
          activateAt
          concludeAt
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Rollout/179220554"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'query RolloutSchedule($id: ID!) {
  rollout(id: $id) {
    id
    schedule {
      activateAt
      concludeAt
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Rollout/179220554"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query RolloutSchedule($id: ID!) {
        rollout(id: $id) {
          id
          schedule {
            activateAt
            concludeAt
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Rollout/179220554"
    },
  }),
});

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

Response

{
  "rollout": {
    "id": "gid://shopify/Rollout/179220554",
    "schedule": {
      "activateAt": "2026-10-10T10:00:00Z",
      "concludeAt": "2026-10-11T10:00:00Z"
    }
  }
}

Examples

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

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

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

const response = await admin.graphql(

`#graphql

query ReadRolloutChangeIdentities($id: ID!) {

rollout(id: $id) {

name

treatments {

changes(first: 10, reverse: false) {

nodes {

__typename

}

pageInfo {

hasNextPage

endCursor

}

}`,

{

variables: {

"id": "gid://shopify/Rollout/532060658"

);

const json = await response.json();

return json.data;

}

GQL

query ReadRolloutChangeIdentities($id: ID!) {
  rollout(id: $id) {
    id
    name
    treatments {
      id
      changes(first: 10, reverse: false) {
        nodes {
          id
          __typename
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query ReadRolloutChangeIdentities($id: ID!) { rollout(id: $id) { id name treatments { id changes(first: 10, reverse: false) { nodes { id __typename } pageInfo { hasNextPage endCursor } } } } }",
 "variables": {
    "id": "gid://shopify/Rollout/532060658"
  }
}'

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 ReadRolloutChangeIdentities($id: ID!) {
    rollout(id: $id) {
      id
      name
      treatments {
        id
        changes(first: 10, reverse: false) {
          nodes {
            id
            __typename
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Rollout/532060658"
    },
  },
  );
  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 ReadRolloutChangeIdentities($id: ID!) {
      rollout(id: $id) {
        id
        name
        treatments {
          id
          changes(first: 10, reverse: false) {
            nodes {
              id
              __typename
            }
            pageInfo {
              hasNextPage
              endCursor
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Rollout/532060658"
    },
  },
});

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 ReadRolloutChangeIdentities($id: ID!) {
    rollout(id: $id) {
      id
      name
      treatments {
        id
        changes(first: 10, reverse: false) {
          nodes {
            id
            __typename
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Rollout/532060658"
}

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

Shopify CLI

shopify app execute \
--query \
'query ReadRolloutChangeIdentities($id: ID!) {
  rollout(id: $id) {
    id
    name
    treatments {
      id
      changes(first: 10, reverse: false) {
        nodes {
          id
          __typename
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/Rollout/532060658"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      query ReadRolloutChangeIdentities($id: ID!) {
        rollout(id: $id) {
          id
          name
          treatments {
            id
            changes(first: 10, reverse: false) {
              nodes {
                id
                __typename
              }
              pageInfo {
                hasNextPage
                endCursor
              }
            }
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/Rollout/532060658"
    },
  }),
});

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

Input variables

JSON

{

"id": "gid://shopify/Rollout/532060658"

}

Response

JSON

{

"rollout": {

"id": "gid://shopify/Rollout/532060658",

"name": "Black Friday offer changeover",

"treatments": [

{

"id": "gid://shopify/RolloutTreatment/522314081",

"changes": {

"nodes": [

{

"id": "gid://shopify/RolloutDiscountActivateChange/19562284969ac8973c308a5159bf122bb6cc5966282d620bfbf81e7029f1e686",

"__typename": "RolloutDiscountActivateChange"

{

"id": "gid://shopify/RolloutDiscountExpireChange/c2f0dd9c068a6dba4866e563632bc485070d427fd72568094e761b30fa639467",

"__typename": "RolloutDiscountExpireChange"

}

"pageInfo": {

"hasNextPage": false,

"endCursor": "WzEsIjQ4NDYzOWJkYmU5NTExNjA4NDJiYTNhNzJiYjEyYWE4MjhjZmJjNmFiNjU4YTI0YWYwZTZmZTUxN2JhMzM4M2EiLCIyMDI2LTExLTAxVDAwOjAwOjAwLjAwMDAwMDAwMFoiLDEsImMyZjBkZDljMDY4YTZkYmE0ODY2ZTU2MzYzMmJjNDg1MDcwZDQyN2ZkNzI1NjgwOTRlNzYxYjMwZmE2Mzk0NjciXQ"

}

{

"id": "gid://shopify/RolloutTreatment/755492298",

"changes": {

"nodes": [],

"pageInfo": {

"hasNextPage": false,

"endCursor": null

}

]

}