creative designer

When I look back at a Shopify traffic report, I want to know what changed around the time the numbers moved. If I shipped a different navigation or changed a product page, I'd rather see the date on the chart than dig through Git to figure out when it went live.

Shopify Analytics already records when a theme is published. On Freakdesign I can see recent theme publishes, each listed by theme name. The next day I tweaked some header text on the theme that was already live. The context I’d want to see when I come back to the chart is what changed: I replaced the an out of date subline with a newer one. The commit for that change was 61e9cef.

Shopify's Fall ’26 Edition added a way for apps to write annotations to Analytics. The GraphQL call takes a title and timestamp and adds a marker to the report. The description is where I’d put what shipped and the commit hash.

Try it on a dev store

The example below uses the Shopify CLI and the write_analytics_annotations scope on a dev store. Set the timestamp to when the release went live. Running it creates one marker, so run it once per release.

shopify store execute --store your-dev-store.myshopify.com \--version 2026-10 --allow-mutations \--query 'mutation ReleaseNote($input: AnalyticsAnnotationCreateInput!) {analyticsAnnotationCreate(input: $input) {analyticsAnnotation { id title startedAt }userErrors { field message }}}' \--variables '{"input":{"type":"other","title":"Homepage subtitle updated","startedAt":"2026-11-14T20:45:00+11:00","description":"Replaced the content with something better for the audience. Commit 61e9cef."}}'

The timestamp in the example is illustrative. I used Shopify’s other type for routine releases. Shopify also has a store_redesign type for bigger changes to the storefront.

If you're a dev, you should see the value in doing this.

See the release on the chart

In Shopify Analytics, I opened Sessions over time and grouped the report by day. The date range includes the homepage update, and the annotation filter shows custom events of type Other.

FROM sessionsSHOW sessionsWHERE human_or_bot_session = 'human'TIMESERIES daySINCE 2026-11-12 UNTIL 2026-11-15ORDER BY day ASCVISUALIZE sessions TYPE lineANNOTATE custom_events.other

I added the release note in Admin for the screenshot. The CLI example still needs an end-to-end run on a dev store.

ShopifyQL sessions query beside the saved Homepage subtitle updated annotation

The ShopifyQL query and the release note added

Fall ’26 Edition · Admin API mutation · ShopifyQL annotation types

Like to work with me?

Let's talk