Choose a version:

analyticsAnnotationUpdate

mutation

Requires Requires write_analytics_annotations access scope.

Updates an existing analytics annotation. Only the fields provided in the input argument are modified; omitted fields remain unchanged. Setting endedAt to null makes the annotation open-ended.

An app can update only annotations that it created. If an app attempts to update an annotation that it didn't create, then the mutation returns a NOT_FOUND error.

Use analyticsAnnotationCreate to create a new annotation, or analyticsAnnotationDelete to remove it.

If provided, 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 idid

•ID!

required

The ID of the analytics annotation to update.

Anchor to inputinput

•AnalyticsAnnotationUpdateInput!

required

The input fields for updating the analytics annotation.

Was this section helpful?

Anchor to AnalyticsAnnotationUpdatePayload returnsAnalyticsAnnotationUpdatePayload returns

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

Was this section helpful?

Examples

Update an analytics annotation

Description

Update an app-authored annotation created by the same app.

Query

mutation analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
  analyticsAnnotationUpdate(id: $id, input: $input) {
    analyticsAnnotation {
      id
      type
      title
      startedAt
      endedAt
      description
      createdByApp {
        id
        title
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "id": "gid://shopify/AnalyticsAnnotation/1234567890",
  "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) { analyticsAnnotationUpdate(id: $id, input: $input) { analyticsAnnotation { id type title startedAt endedAt description createdByApp { id title } } userErrors { field message code } } }",
 "variables": {
    "id": "gid://shopify/AnalyticsAnnotation/1234567890",
    "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
    analyticsAnnotationUpdate(id: $id, input: $input) {
      analyticsAnnotation {
        id
        type
        title
        startedAt
        endedAt
        description
        createdByApp {
          id
          title
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/AnalyticsAnnotation/1234567890",
        "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
    analyticsAnnotationUpdate(id: $id, input: $input) {
      analyticsAnnotation {
        id
        type
        title
        startedAt
        endedAt
        description
        createdByApp {
          id
          title
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/AnalyticsAnnotation/1234567890",
  "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
      analyticsAnnotationUpdate(id: $id, input: $input) {
        analyticsAnnotation {
          id
          type
          title
          startedAt
          endedAt
          description
          createdByApp {
            id
            title
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/AnalyticsAnnotation/1234567890",
        "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
  analyticsAnnotationUpdate(id: $id, input: $input) {
    analyticsAnnotation {
      id
      type
      title
      startedAt
      endedAt
      description
      createdByApp {
        id
        title
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/AnalyticsAnnotation/1234567890",
  "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
        analyticsAnnotationUpdate(id: $id, input: $input) {
          analyticsAnnotation {
            id
            type
            title
            startedAt
            endedAt
            description
            createdByApp {
              id
              title
            }
          }
          userErrors {
            field
            message
            code
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/AnalyticsAnnotation/1234567890",
        "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

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

analyticsAnnotationUpdate 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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {

analyticsAnnotationUpdate(id: $id, input: $input) {

analyticsAnnotation {

type

title

startedAt

endedAt

description

createdByApp {

title

}

userErrors {

field

message

code

}

}`,

{

variables: {

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

"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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
  analyticsAnnotationUpdate(id: $id, 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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) { analyticsAnnotationUpdate(id: $id, input: $input) { analyticsAnnotation { id type title startedAt endedAt description createdByApp { id title } } userErrors { field message code } } }",
 "variables": {
    "id": "gid://shopify/AnalyticsAnnotation/1234567890",
    "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
    analyticsAnnotationUpdate(id: $id, input: $input) {
      analyticsAnnotation {
        id
        type
        title
        startedAt
        endedAt
        description
        createdByApp {
          id
          title
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/AnalyticsAnnotation/1234567890",
        "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
      analyticsAnnotationUpdate(id: $id, input: $input) {
        analyticsAnnotation {
          id
          type
          title
          startedAt
          endedAt
          description
          createdByApp {
            id
            title
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/AnalyticsAnnotation/1234567890",
        "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
    analyticsAnnotationUpdate(id: $id, input: $input) {
      analyticsAnnotation {
        id
        type
        title
        startedAt
        endedAt
        description
        createdByApp {
          id
          title
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/AnalyticsAnnotation/1234567890",
  "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
  analyticsAnnotationUpdate(id: $id, input: $input) {
    analyticsAnnotation {
      id
      type
      title
      startedAt
      endedAt
      description
      createdByApp {
        id
        title
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}' \
--variables \
'{
  "id": "gid://shopify/AnalyticsAnnotation/1234567890",
  "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 analyticsAnnotationUpdate($id: ID!, $input: AnalyticsAnnotationUpdateInput!) {
        analyticsAnnotationUpdate(id: $id, input: $input) {
          analyticsAnnotation {
            id
            type
            title
            startedAt
            endedAt
            description
            createdByApp {
              id
              title
            }
          }
          userErrors {
            field
            message
            code
          }
        }
      }
    `,
    variables: {
        "id": "gid://shopify/AnalyticsAnnotation/1234567890",
        "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

{

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

"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

{

"analyticsAnnotationUpdate": {

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

}