Choose a version:

analyticsAnnotationCreate

mutation

Requires Requires write_analytics_annotations access scope.

Creates an analytics annotation on the shop. Annotations are notable events that can be overlaid on analytics charts to provide context for changes in metrics. The annotation is attributed to the app that calls the mutation.

Shopify limits how many annotations an app can have for a shop. If the app reaches this limit, then the mutation returns a LIMIT_REACHED error. Delete existing annotations or contact Shopify Support to request a higher limit.

Use analyticsAnnotationUpdate to modify existing annotations or analyticsAnnotationDelete to remove them.

The type field must specify a supported type for app-created annotations. Refer to the list of supported types.

Anchor to Arguments

Arguments

Anchor to inputinput

•AnalyticsAnnotationCreateInput!

required

The input fields for creating an analytics annotation.

Was this section helpful?

Anchor to AnalyticsAnnotationCreatePayload returnsAnalyticsAnnotationCreatePayload returns

Anchor to analyticsAnnotationanalyticsAnnotation •AnalyticsAnnotation: The newly created analytics annotation.
Anchor to userErrorsuserErrors •[AnalyticsAnnotationCreateUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Create an analytics annotation

Description

Create an app-authored annotation that can be overlaid on analytics charts.

Query

mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
  analyticsAnnotationCreate(input: $input) {
    analyticsAnnotation {
      id
      type
      title
      startedAt
      endedAt
      description
      createdByApp {
        id
        title
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "input": {
    "type": "campaign",
    "title": "Brightleaf Campaigns BFCM 12-email cadence",
    "startedAt": "2026-11-28T00:00:00Z",
    "endedAt": "2026-12-01T00:00:00Z",
    "description": "Sent to lapsed-90-day segment; $96 RPR target"
  }
}

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": "mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) { analyticsAnnotationCreate(input: $input) { analyticsAnnotation { id type title startedAt endedAt description createdByApp { id title } } userErrors { field message code } } }",
 "variables": {
    "input": {
      "type": "campaign",
      "title": "Brightleaf Campaigns BFCM 12-email cadence",
      "startedAt": "2026-11-28T00:00:00Z",
      "endedAt": "2026-12-01T00:00:00Z",
      "description": "Sent to lapsed-90-day segment; $96 RPR target"
    }
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
    analyticsAnnotationCreate(input: $input) {
      analyticsAnnotation {
        id
        type
        title
        startedAt
        endedAt
        description
        createdByApp {
          id
          title
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "input": {
            "type": "campaign",
            "title": "Brightleaf Campaigns BFCM 12-email cadence",
            "startedAt": "2026-11-28T00:00:00Z",
            "endedAt": "2026-12-01T00:00:00Z",
            "description": "Sent to lapsed-90-day segment; $96 RPR target"
        }
    },
  },
  );
  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
  mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
    analyticsAnnotationCreate(input: $input) {
      analyticsAnnotation {
        id
        type
        title
        startedAt
        endedAt
        description
        createdByApp {
          id
          title
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "input": {
    "type": "campaign",
    "title": "Brightleaf Campaigns BFCM 12-email cadence",
    "startedAt": "2026-11-28T00:00:00Z",
    "endedAt": "2026-12-01T00:00:00Z",
    "description": "Sent to lapsed-90-day segment; $96 RPR target"
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
      analyticsAnnotationCreate(input: $input) {
        analyticsAnnotation {
          id
          type
          title
          startedAt
          endedAt
          description
          createdByApp {
            id
            title
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "input": {
            "type": "campaign",
            "title": "Brightleaf Campaigns BFCM 12-email cadence",
            "startedAt": "2026-11-28T00:00:00Z",
            "endedAt": "2026-12-01T00:00:00Z",
            "description": "Sent to lapsed-90-day segment; $96 RPR target"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
  analyticsAnnotationCreate(input: $input) {
    analyticsAnnotation {
      id
      type
      title
      startedAt
      endedAt
      description
      createdByApp {
        id
        title
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}' \
--variables \
'{
  "input": {
    "type": "campaign",
    "title": "Brightleaf Campaigns BFCM 12-email cadence",
    "startedAt": "2026-11-28T00:00:00Z",
    "endedAt": "2026-12-01T00:00:00Z",
    "description": "Sent to lapsed-90-day segment; $96 RPR target"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
        analyticsAnnotationCreate(input: $input) {
          analyticsAnnotation {
            id
            type
            title
            startedAt
            endedAt
            description
            createdByApp {
              id
              title
            }
          }
          userErrors {
            field
            message
            code
          }
        }
      }
    `,
    variables: {
        "input": {
            "type": "campaign",
            "title": "Brightleaf Campaigns BFCM 12-email cadence",
            "startedAt": "2026-11-28T00:00:00Z",
            "endedAt": "2026-12-01T00:00:00Z",
            "description": "Sent to lapsed-90-day segment; $96 RPR target"
        }
    },
  }),
});

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

Response

{
  "analyticsAnnotationCreate": {
    "analyticsAnnotation": {
      "id": "gid://shopify/AnalyticsAnnotation/1234567890",
      "type": "campaign",
      "title": "Brightleaf Campaigns BFCM 12-email cadence",
      "startedAt": "2026-11-28T00:00:00Z",
      "endedAt": "2026-12-01T00:00:00Z",
      "description": "Sent to lapsed-90-day segment; $96 RPR target",
      "createdByApp": {
        "id": "gid://shopify/App/123456",
        "title": "Brightleaf Campaigns"
      }
    },
    "userErrors": []
  }
}

analyticsAnnotationCreate reference

Examples

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

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

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

const response = await admin.graphql(

`#graphql

mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {

analyticsAnnotationCreate(input: $input) {

analyticsAnnotation {

type

title

startedAt

endedAt

description

createdByApp {

title

}

userErrors {

field

message

code

}

}`,

{

variables: {

"input": {

"type": "campaign",

"title": "Brightleaf Campaigns BFCM 12-email cadence",

"startedAt": "2026-11-28T00:00:00Z",

"endedAt": "2026-12-01T00:00:00Z",

"description": "Sent to lapsed-90-day segment; $96 RPR target"

}

);

const json = await response.json();

return json.data;

}

GQL

mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
  analyticsAnnotationCreate(input: $input) {
    analyticsAnnotation {
      id
      type
      title
      startedAt
      endedAt
      description
      createdByApp {
        id
        title
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

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": "mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) { analyticsAnnotationCreate(input: $input) { analyticsAnnotation { id type title startedAt endedAt description createdByApp { id title } } userErrors { field message code } } }",
 "variables": {
    "input": {
      "type": "campaign",
      "title": "Brightleaf Campaigns BFCM 12-email cadence",
      "startedAt": "2026-11-28T00:00:00Z",
      "endedAt": "2026-12-01T00:00:00Z",
      "description": "Sent to lapsed-90-day segment; $96 RPR target"
    }
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
    analyticsAnnotationCreate(input: $input) {
      analyticsAnnotation {
        id
        type
        title
        startedAt
        endedAt
        description
        createdByApp {
          id
          title
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "input": {
            "type": "campaign",
            "title": "Brightleaf Campaigns BFCM 12-email cadence",
            "startedAt": "2026-11-28T00:00:00Z",
            "endedAt": "2026-12-01T00:00:00Z",
            "description": "Sent to lapsed-90-day segment; $96 RPR target"
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
      analyticsAnnotationCreate(input: $input) {
        analyticsAnnotation {
          id
          type
          title
          startedAt
          endedAt
          description
          createdByApp {
            id
            title
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "input": {
            "type": "campaign",
            "title": "Brightleaf Campaigns BFCM 12-email cadence",
            "startedAt": "2026-11-28T00:00:00Z",
            "endedAt": "2026-12-01T00:00:00Z",
            "description": "Sent to lapsed-90-day segment; $96 RPR target"
        }
    },
  },
});

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 analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
    analyticsAnnotationCreate(input: $input) {
      analyticsAnnotation {
        id
        type
        title
        startedAt
        endedAt
        description
        createdByApp {
          id
          title
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "input": {
    "type": "campaign",
    "title": "Brightleaf Campaigns BFCM 12-email cadence",
    "startedAt": "2026-11-28T00:00:00Z",
    "endedAt": "2026-12-01T00:00:00Z",
    "description": "Sent to lapsed-90-day segment; $96 RPR target"
  }
}

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

Shopify CLI

shopify app execute \
--query \
'mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
  analyticsAnnotationCreate(input: $input) {
    analyticsAnnotation {
      id
      type
      title
      startedAt
      endedAt
      description
      createdByApp {
        id
        title
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}' \
--variables \
'{
  "input": {
    "type": "campaign",
    "title": "Brightleaf Campaigns BFCM 12-email cadence",
    "startedAt": "2026-11-28T00:00:00Z",
    "endedAt": "2026-12-01T00:00:00Z",
    "description": "Sent to lapsed-90-day segment; $96 RPR target"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation analyticsAnnotationCreate($input: AnalyticsAnnotationCreateInput!) {
        analyticsAnnotationCreate(input: $input) {
          analyticsAnnotation {
            id
            type
            title
            startedAt
            endedAt
            description
            createdByApp {
              id
              title
            }
          }
          userErrors {
            field
            message
            code
          }
        }
      }
    `,
    variables: {
        "input": {
            "type": "campaign",
            "title": "Brightleaf Campaigns BFCM 12-email cadence",
            "startedAt": "2026-11-28T00:00:00Z",
            "endedAt": "2026-12-01T00:00:00Z",
            "description": "Sent to lapsed-90-day segment; $96 RPR target"
        }
    },
  }),
});

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

Input variables

JSON

{

"input": {

"type": "campaign",

"title": "Brightleaf Campaigns BFCM 12-email cadence",

"startedAt": "2026-11-28T00:00:00Z",

"endedAt": "2026-12-01T00:00:00Z",

"description": "Sent to lapsed-90-day segment; $96 RPR target"

}

Response

JSON

{

"analyticsAnnotationCreate": {

"analyticsAnnotation": {

"id": "gid://shopify/AnalyticsAnnotation/1234567890",

"type": "campaign",

"title": "Brightleaf Campaigns BFCM 12-email cadence",

"startedAt": "2026-11-28T00:00:00Z",

"endedAt": "2026-12-01T00:00:00Z",

"description": "Sent to lapsed-90-day segment; $96 RPR target",

"createdByApp": {

"id": "gid://shopify/App/123456",

"title": "Brightleaf Campaigns"

}

"userErrors": []

}