---
title: analyticsAnnotationCreate - GraphQL Admin
description: >-
  Creates an [analytics
  annotation](https://shopify.dev/docs/api/admin-graphql/latest/objects/AnalyticsAnnotation)

  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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationUpdate)

  to modify existing annotations or

  [`analyticsAnnotationDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationDelete)

  to remove them.


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

  [supported
  types](https://shopify.dev/docs/api/shopifyql/latest/syntax/annotate#annotation-categories-and-types).
api_version: 2026-10
source_url:
  html: >-
    https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationCreate
  md: >-
    https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationCreate.md
api_name: admin
api_type: graphql
type: mutation
---

# analytics​Annotation​Create

mutation

Requires Requires `write_analytics_annotations` access scope.

Creates an [analytics annotation](https://shopify.dev/docs/api/admin-graphql/latest/objects/AnalyticsAnnotation) 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationUpdate) to modify existing annotations or [`analyticsAnnotationDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationDelete) to remove them.

The `type` field must specify a supported type for app-created annotations. Refer to the list of [supported types](https://shopify.dev/docs/api/shopifyql/latest/syntax/annotate#annotation-categories-and-types).

## Arguments

* input

  [Analytics​Annotation​Create​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/AnalyticsAnnotationCreateInput)

  required

  The input fields for creating an analytics annotation.

***

## Analytics​Annotation​Create​Payload returns

* analytics​Annotation

  [Analytics​Annotation](https://shopify.dev/docs/api/admin-graphql/latest/objects/AnalyticsAnnotation)

  The newly created analytics annotation.

* user​Errors

  [\[Analytics​Annotation​Create​User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/AnalyticsAnnotationCreateUserError)

  non-null

  The list of errors that occurred from executing the mutation.

***

## Examples

* ### Create an analytics annotation

  #### Description

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

  #### Query

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

  #### 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"
    }
  }
  ```

  #### cURL

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

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

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

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

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

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

  ```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": []
    }
  }
  ```

* ### analyticsAnnotationCreate reference