7/22/2026, 12:00:14 AM
Shopify now supports creating, updating and deleting analytics annotations, a new set of mutations that let apps mark events on shop analytics charts. Annotation creation requires a non‑null locationId for inventoryCountCreate, making the field mandatory. The new payload types expose detailed user errors, including LIMIT_REACHED for annotations and COMPARE_QUANTITY_STALE for inventory counts. Apps can query a shop’s annotations via the added analyticsAnnotations field, supporting pagination, sorting by date/time and filtering by title, type, source and date ranges. Annotation objects deliver metadata such as createdByApp, source (SHOPIFY or APP), and timestamps; app‑created annotations have 75‑character title and 150‑character description limits. The ShopifyqlQueryResponse type gained parseWarnings to surface non‑fatal parse messages without blocking results. All new objects, input types, and enums are documented and errors now return standardized codes like NOT_FOUND, INVALID, SHOPIFY_EMPLOYEE_IMPERSONATING.
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 oranalyticsAnnotationDelete
to remove them.
The type field must specify a supported type for app-created annotations. Refer to the list of
supported types.
Deletes an analytics annotation.
An app can delete only annotations that it created. If an app attempts to delete an annotation that it
didn't create, then the mutation returns a NOT_FOUND error.
Use analyticsAnnotationCreate
to create a new annotation, oranalyticsAnnotationUpdate
to modify existing ones.
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, oranalyticsAnnotationDelete
to remove it.
If provided, the type field must specify a supported type for app-created annotations. Refer to the list of
supported types.
Creates an inventory count for auditing and adjusting stock levels at a specific location.
Note:
This mutation is available only in the unstable API version and to development stores
that have enabled the Physical inventory feature preview.
An annotation for a notable event on a shop's analytics timeline.
An auto-generated type for paginating through multiple AnalyticsAnnotations.
The input fields for creating an analytics annotation.
Return type for analyticsAnnotationCreate mutation.
An error that occurs during the execution of AnalyticsAnnotationCreate.
Possible error codes that can be returned by AnalyticsAnnotationCreateUserError.
Return type for analyticsAnnotationDelete mutation.
An error that occurs during the execution of AnalyticsAnnotationDelete.
Possible error codes that can be returned by AnalyticsAnnotationDeleteUserError.
An auto-generated type which holds one AnalyticsAnnotation and a cursor during pagination.
The set of valid sort keys for the AnalyticsAnnotation query.
Identifies who or what created an analytics annotation.
The input fields for updating an analytics annotation. Only the fields you provide are changed.
Return type for analyticsAnnotationUpdate mutation.
An error that occurs during the execution of AnalyticsAnnotationUpdate.
Possible error codes that can be returned by AnalyticsAnnotationUpdateUserError.
COMPARE_QUANTITY_STALEanalyticsAnnotationsReturns a paginated list of analytics annotations
for the shop, including Shopify-generated annotations and annotations created by any app. Annotations are
markers that can be overlaid on analytics charts to give merchants context for changes in their metrics.
Supports filtering by title, type, source, start date and time, end date and time, creation date and time, and
update date and time. Results can be sorted by ID or by any of the supported date and time fields. Use theanalyticsAnnotationCreate
mutation to add new app-created annotations.
parseWarningsA list of non-fatal parse warnings, such as use of a deprecated field. Unlike parseErrors, warnings are returned alongside results.