--- title: AnalyticsAnnotation - GraphQL Admin description: An annotation for a notable event on a shop's analytics timeline. api_version: 2026-10 source_url: html: >- https://shopify.dev/docs/api/admin-graphql/latest/objects/AnalyticsAnnotation md: >- https://shopify.dev/docs/api/admin-graphql/latest/objects/AnalyticsAnnotation.md api_name: admin api_type: graphql type: object --- # Analytics​Annotation object Requires Requires `read_analytics_annotations` or `write_analytics_annotations` access scope. An annotation for a notable event on a shop's analytics timeline. ## Fields * created​At [Date​Time](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) The date and time when the annotation was created. * created​By​App [App](https://shopify.dev/docs/api/admin-graphql/latest/objects/App) The app that created the annotation. Returns `null` if the annotation wasn't created by an app. * description [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) A plain-text description that provides additional context about the annotation. The maximum length is 150 characters for app-created annotations. * ended​At [Date​Time](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) The date and time when the annotation ended. Returns `null` if the annotation is open-ended. * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) non-null A globally-unique ID. * source [Analytics​Annotation​Source!](https://shopify.dev/docs/api/admin-graphql/latest/enums/AnalyticsAnnotationSource) non-null Identifies who or what created this annotation. * started​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) non-null The date and time when the annotation started. * title [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The title of the annotation. The maximum length is 75 characters for app-created annotations. * type [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The type of event represented by the annotation. Refer to the list of [supported types](https://shopify.dev/docs/api/shopifyql/latest/syntax/annotate#annotation-categories-and-types). * updated​At [Date​Time](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) The date and time when the annotation was last updated. *** ## Map ### Fields and connections with this object * [AnalyticsAnnotationConnection.nodes](https://shopify.dev/docs/api/admin-graphql/latest/connections/AnalyticsAnnotationConnection#returns-nodes) * [AnalyticsAnnotationEdge.node](https://shopify.dev/docs/api/admin-graphql/latest/objects/AnalyticsAnnotationEdge#field-AnalyticsAnnotationEdge.fields.node) * [Shop.analyticsAnnotations](https://shopify.dev/docs/api/admin-graphql/latest/objects/Shop#field-Shop.fields.analyticsAnnotations) *** ## Mutations * [analytics​Annotation​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationCreate) mutation 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). * input [Analytics​Annotation​Create​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/AnalyticsAnnotationCreateInput) required ### Arguments The input fields for creating an analytics annotation. *** * [analytics​Annotation​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationUpdate) mutation Updates an existing [analytics annotation](https://shopify.dev/docs/api/admin-graphql/latest/objects/AnalyticsAnnotation). 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationCreate) to create a new annotation, or [`analyticsAnnotationDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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](https://shopify.dev/docs/api/shopifyql/latest/syntax/annotate#annotation-categories-and-types). * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) required ### Arguments The ID of the analytics annotation to update. * input [Analytics​Annotation​Update​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/AnalyticsAnnotationUpdateInput) required The input fields for updating the analytics annotation. *** *** ## AnalyticsAnnotation Mutations ### Mutated by * [analytics​Annotation​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationCreate) * [analytics​Annotation​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/analyticsAnnotationUpdate) *** ## Interfaces * [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node) interface *** ## AnalyticsAnnotation Implements ### Implements * [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)