Classification of the feature
Since July 29, 2026, Shopify has also been showing annotations in analytics charts that are created by installed apps. An annotation marks an event on a specific day or within a certain time period. In the admin, Shopify also shows which app created the annotation. This allows merchants to compare, for example, campaigns, product launches, supplier changes, or new landing pages with the development of their key metrics. The annotation does not change any report data; it simply adds business context to it.
What the feature is and what it is not
A temporal marker for business events
An annotation is a visible marker below an analytics chart. It indicates that at this point in time an event occurred that may be relevant for interpreting the metrics.
This can be compared to a note in a calendar. The note doesn’t change what happened on that day. But it helps to put the event back into context later.
Shopify distinguishes between two sources.
Shopify can automatically flag certain store activities. These include products that were published or deactivated, themes that were published, apps that were installed or uninstalled, changes to metric definitions, and periods with missing data.
Installed apps can flag additional events. Supported examples include product launches, campaigns, price promotions, changes to the advertising budget, new payment methods, inventory changes, market entries, loyalty programs, and external events.
No evidence of cause and effect
An annotation shows a temporal relationship. It does not prove that an event caused a change.
If sales increase after the launch of a campaign, the campaign may have played a role. At the same time, however, a public holiday, media coverage, a change in demand, or an action by a competitor could also have influenced sales.
A factually correct statement therefore is
After the campaign launch, sales increased. The effect should now be analyzed by market, channel, product group, and customer type.
A statement that goes too far would be
The campaign caused the increase in sales.
Shopify explicitly describes annotations as additional context that can help investigate possible influences on metrics.
No substitute for a controlled test
An annotation is no substitute for an A/B test or a control group.
For example, if you roll out a new layout for the product detail page, you can compare the conversion rate before and after the launch. However, this comparison alone still doesn’t show whether the layout was actually responsible for the change.
To do this, you would need to take into account, among other things, seasonal effects, devices, countries, products, and changes carried out at the same time.
No complete project archive
An annotation may only contain a brief summary. Technical decisions, approvals, error analyses, and rollback instructions should still be documented in a ticket or project system.
The annotation serves as a visible link between the event and the metrics. It does not replace the detailed documentation of the event.
No freely editable note function in the admin area
According to the current Shopify documentation, merchants cannot create arbitrary custom annotations directly in the Shopify admin.
Annotations are either generated automatically from the shop’s activities or created by an installed app. Anyone who wants to mark internal company events therefore needs an app that supports these events, or a custom-built integration.
Requirements and data basis
The report requires a time dimension
Annotations can only appear in reports whose horizontal axis uses a time dimension. This includes, for example, daily, weekly, and monthly trends.
Visualizations without a time axis do not support annotations. Shopify lists tables, donut charts, and cohort views among others.
Multi-store reports also currently do not show any annotations. When exporting a report, the markers are likewise not included. For corporate groups with multiple shops and for external analyses, an additional event log is therefore often still necessary.
Shopify does not create automatic annotations in every store
Minimum requirements apply to annotations automatically generated by Shopify.
The shop must have achieved an average of ten or more orders per week in at least twelve non-consecutive weeks within the past six months. In addition, at least one order must have been received within the past two weeks.
These requirements refer to Shopify-generated annotations. For annotations created by apps, Shopify does not specify any corresponding minimum order quantity in this merchant documentation.
What this means in practice
A smaller or seasonal shop may be able to see app annotations, even though Shopify itself does not yet generate automatic shop activities as annotations.
The app used must support annotations
Not every installed app automatically creates annotations.
The app provider must implement the function technically and define which events are transmitted to Shopify. For example, a marketing app could tag campaigns. A fulfillment app could document changes in warehouses or service providers.
For entries created by apps, Shopify displays the name or icon of the app responsible. This makes it clear which system the context comes from.
The selected key figure must match the question at hand
An annotation is only useful when it is viewed together with an appropriate metric.
When creating a new shipping cost rule, you should not look only at total revenue. Depending on the question at hand, these additional values are also relevant.
- Conversion Rate
- average order value
- abandoned checkouts
- Orders by delivery country
- selected shipping methods
- return rate
- Time to fulfillment
For a new B2B price list, however, the order value, order frequency, and revenue per company may be more important than the overall number of sessions.
A practical rule is
If an annotation describes a business event, it should already be clear in advance which key figure would show any potential change.
Consent affects part of the data that is evaluated
The annotation itself does not require a shop visitor’s consent. It describes a business event.
However, the session and attribution data considered alongside this can be affected by privacy settings. If visitors do not consent to analytics, fewer sessions may be recorded. As a result, session-based conversion rates and marketing analyses may also be incomplete.
Orders and revenue, on the other hand, are based on recorded transactions and must be evaluated separately from session-based metrics.
Markets and time zones must be unique
International shops should not describe an event as having been launched only with a campaign if the activity ran exclusively in a specific country.
A better wording would be
AT end-of-summer sale started
or
US market free shipping activated from 100 USD
The time zone must also be clearly defined. A campaign that starts at 11 p.m. German time may fall on a different calendar day in another market.
Technical integrations should therefore store timestamps in a standardized way and prepare them for display in the required time zone.
How to use annotations in the Shopify admin
Open an appropriate report
In the Shopify admin, go to Analytics and then Reports.
Select a report that includes a time dimension. Suitable examples are reports with daily, weekly, or monthly trends.
Show the annotations
Annotations are hidden by default.
In the report, open the visualization settings and enable the display of annotations. Alternatively, you can switch to the annotations panel and make the markers visible there.
A separate time axis then appears below the chart. Smaller and larger dots show how many events there are on a given day.
Filter event types
The filter allows you to show or hide individual activity types.
For a campaign analysis, for example, the following tags may be relevant
- Campaigns
- Changes to the advertising budget
- Discounts
- Product launches
- Landingpage-Starts
For a fulfillment analysis, these events may be more meaningful
- supplier change
- stock transfer
- Change of fulfillment service provider
- external disturbances
The selected filters are saved with the report. The next time you open it, the previously chosen view will be displayed again.
Inspect individual entries
Hover over a marker to see a summary of the events for that day.
Clicking the marker opens the details in the annotations panel. Events generated by the app show the app’s name and icon there.
Shopify displays up to ten events at a time for each activity type. The order is based on business relevance. For product events, for example, products with higher sales are listed first.
This limit does not apply uniformly to all events on a given day. It applies to the respective activity type within the panel.
Choose an appropriate comparison period
The days immediately before and after an event are not always the best comparison.
During an Easter promotion, comparing with the previous week can be misleading. Easter falls on a different date every year. For international shops, local holidays, sales days, and seasonal patterns also need to be taken into account.
For recurring actions, it may be more useful to compare them with the same event from the previous year.
Narrow down noticeable changes
If a clear change becomes visible after an annotation, the report should be further divided step by step.
Practical rules are
- If total revenue increases, then break it down by market and sales channel.
- If the conversion rate drops, then break it down by device and landing page.
- If the order value increases, then review discounts and product mix.
- If fulfillment time increases, compare warehouse locations and service providers.
- If B2B sales are declining, then analyze companies, price lists, and payment terms separately.
The annotation shows a possible starting point. The segmentation shows where the change actually occurred.
Practical logic for meaningfulness and maintenance effort
Not every change is a meaningful annotation.
In a larger shop, numerous changes occur every day.
If every small text correction, every stock adjustment, and every product import were flagged, the timeline would quickly become cluttered.
A simple selection rule states
If an event could trigger a visible change in a business metric, an annotation is probably useful.
Correcting a single typographical error usually does not meet this rule.
They are more likely to be met by a new checkout offer, a change of payment provider, or a significant adjustment to the advertising budget.
The timing and duration must match the measure
A product launch is often a one-off event.
A campaign, a special offer, or a disruption, on the other hand, can run for several days. The API therefore supports a start time and an optional end date.
If a four-week campaign is only tagged on its first day, the immediately visible context is missing in the following weeks.
The technical event type cannot be chosen freely
The visible title of an annotation can be worded individually. However, the technical event type must be one of the types supported by Shopify.
These include, among other things, campaigns, product launches, store redesigns, price promotions, inventory changes, market shifts, and external events.
If a strategic change does not fit into any existing category, an app can use the general type Other.
For a new B2B price list, depending on how it is implemented, the Market change type might be appropriate. If that’s not the case, the app should use Other and clearly describe the change in the title.
Simultaneous changes make interpretation more difficult
If you release a new theme, launch a discount, increase your advertising budget, and activate a new payment method all on the same day, it’s almost impossible to attribute any later effect to a single one of those changes.
Annotations make this overlap visible. However, they do not solve the problem.
Business‑critical changes should therefore, if possible, be separated in time. If that is not possible, additional metrics and comparison groups should be defined in advance.
Apps cannot store annotations indefinitely
Shopify limits the number of annotations that an app can create for a store.
The official API documentation does not specify a general fixed number. If the limit is reached, the interface returns the error LIMIT_REACHED. In this case, Shopify recommends deleting existing annotations or contacting support to request a higher limit.
An app therefore shouldn’t automatically save every small action as an annotation.
Title and description are limited
The current API documentation specifies these limits
- Title with a maximum of 75 characters
- Description with a maximum of 150 characters
The title appears on the marker in the chart. The description provides additional context.
General phrases like “update completed” are hardly helpful anymore after a few months.
Typical practical applications
Campaigns and promotions
A marketing app can mark the beginning and end of a campaign.
In the report, you can then check how revenue, conversion rate, order value, and units sold developed over this period.
For example, a shop launches a 15 percent discount on selected jackets. Revenue increases by 20 percent, while at the same time the average order value decreases.
The campaign coincided with higher revenue and a lower average order value. Whether it was economically successful can only be assessed once margins, advertising costs, discount costs, and the share of new customers are taken into account.
Product and collection launches
For a product launch, the annotation can be compared with revenue, units sold, and sessions on the product page.
Additionally, it should be checked whether the new item has generated extra revenue or merely shifted sales away from an existing product.
International shops should use separate events when a product does not become available in all markets at the same time.
Theme and landing page changes
An app can mark the launch of a new landing page or a major store redesign.
After the release, you can analyze conversion rate, order value, and sessions. If the conversion rate drops, you should check whether the effect occurs only on mobile devices, in specific browsers, or in individual markets.
An automatically generated theme publication by Shopify and a redesign annotation created by an app can serve different purposes.
The automatic label shows when a theme was published. The app annotation can additionally describe what the goal of the relaunch was and which metrics should be monitored.
Changing the warehouse or fulfillment service provider
A new logistics partner can affect fulfillment time, cancellations, support requests, and returns.
An annotation shows from which point in time the new operational structure was active.
This is especially helpful when a problem doesn’t become apparent right away, but only several weeks later.
New markets
When you start out in a new country, several settings often change at the same time.
These include
- Currency
- Prices
- Translations
- Shipping rules
- Payment methods
- Taxes and duties
- Delivery times
A market annotation creates a clear temporal starting point.
In the subsequent analysis, the new market should be considered separately from already established countries.
New B2B rules
In B2B shops, changes to price lists, payment terms, minimum order values, and company locations can be flagged.
The analysis should then only include the affected B2B customers. If D2C orders are included, the effect of the B2B change may disappear in the overall result.
Rule sets for ongoing, business-critical and reactive events
Ongoing measures
Rule
If a measure has a clearly defined start and end, it is created as a time period.
These include campaigns, seasonal discounts, time-limited shipping promotions, and price experiments.
The description should answer
- Which market is affected
- Which target group is affected
- What was changed
- Which key figure should be checked
A suitable example is
DE free shipping from 60 euros. Check order value and conversion.
Business-critical changes
Rule
If a change affects multiple teams, markets, or core processes, it is given a consistent name and a clearly defined owner.
These include
- Theme-Relaunches
- ERP migration
- new warehouse
- market entries
- Checkout modifications
- new B2B pricing models
For these events, it should be determined before the start which reports will be reviewed after one day, one week, and one month.
Reactive events
Rule
If an incident can affect key figures or their measurement, the start and end of the incident are marked.
These include
- Tracking outages
- incorrect prices
- unavailable payment methods
- Fulfillment disruptions
- incorrect product data
- unusual interfaces
A suitable example is as follows
PayPal in AT and DE is unavailable between 10:20 a.m. and 12:45 p.m.
A reactive annotation does not replace complete incident documentation. It merely links the incident to the analysis period.
Text and template examples
In the documented input object, Shopify does not provide its own field for a URL or an external event ID.
An app can therefore transmit the title, description, start time, end time, and event type to Shopify. Detailed links and internal references should be maintained in the source system.
A short ticket identifier can be included in the description as long as this does not exceed the character limit.
Campaign
Title
DE summer promotion launched
Description
15 percent off selected categories until August 10. Check revenue and order value. Ticket MKT-241.
Technical Publication
Title
New product detail page layout released
Description
New image gallery and size selection activated. Check conversion by device and market. Ticket WEB-118.
Logistics
Title
Fulfillment for AT switched to new warehouse
Description
Orders from August 1 via Vienna. Check fulfillment time and cancellations. Ticket OPS-73.
measurement error
Title
Tracking failure in checkout
Description
Checkout events from 10:20 a.m. to 12:45 p.m. are incomplete. Interpret funnel data with caution. Ticket DATA-62.
B2B change
Title
New B2B price list for specialist dealers active
Description
DACH retailers with tiered pricing. Check order value and order frequency. Ticket B2B-39.
The examples each contain three pieces of information
- affected market or target group concerned
- specific change
- metric to be checked
Title and description should be automatically checked against the character limits before submission.
When annotations make sense and when they don’t
Useful for clearly delineated changes
Annotations are useful when an event has a specific point in time or time period and could affect a business metric.
This applies especially when
- the point in time would be difficult to reconstruct later
- multiple teams need the same context
- a measure is to be reassessed after several weeks
- the event originates from an external app
- a rollout affects multiple markets
- a malfunction is affecting report data
Useful when many systems are involved
In larger companies, relevant information is often scattered across advertising platforms, ticketing systems, release tools, ERP, PIM, CRM, and fulfillment systems.
An annotation creates a shared point of reference in the Shopify report.
It does not replace the other systems. However, it shows when you should look there for more information.
Less useful for everyday minor adjustments
If hundreds of prices, stocks, or pieces of content are updated every day, each operation shouldn’t create its own annotation.
A consolidated label is more helpful in that case.
One example is
Autumn range and prices updated for 240 items.
Unsuitable for reliable proof of efficacy
Anyone who wants to prove that a change has caused an effect often needs a controlled test or a comparison group.
A single annotation is not enough for that.
Not suitable as a permanent project archive
The short texts are not suitable for technical root cause analyses, decision logs, or approvals.
This information still belongs in a dedicated system designed for it.
Mistakes to avoid
Too many annotations are being generated
If every small product change and every automatically sent message is flagged, important events get lost among the unimportant entries.
Therefore, define a minimum threshold value.
An annotation should only be created if the event could affect a business-relevant key metric.
Use a vague title
A title like Campaign Launched is of little use after six months.
Better is
AT new customer campaign launched with free shipping.
Submit unsupported event types
The technical type of an annotation cannot be named arbitrarily.
The app must use a supported Shopify type. If no type fits, Other should be used.
The individual content belongs in the title and description.
Mixing markets and target groups
A change that only affects B2B customers in Germany must not be described as if it affected the entire shop.
Market, customer group, and channel should be stated directly in the title or in the description.
Only document the beginning
For campaigns or incidents, the end should also be documented.
Otherwise, it gives the impression that the event was only relevant on one day or is still ongoing.
Confusing temporal proximity with causation
A curve rises after a change. That’s a reason to analyze it, but not yet proof.
Check comparison periods, seasonal effects, and other simultaneous changes.
Store personal data
Annotations must not contain customer names, email addresses, or other personal information.
Instead of naming a single major customer, a neutral description should be used.
One example is
B2B revenue impacted by the loss of a major customer.
Do not document rollbacks
If a change is reverted, the annotation must also be updated.
Otherwise, a later development may be attributed to a function that was already disabled at that time.
Moving Primates Perspective
In larger Shopify projects, the problem is often not the amount of data, but the missing link between metrics and the changes that were made shortly before. A risk arises when apps tag every activity without any filtering, or when teams use different names for the same event. This creates extra noise instead of helpful context. A small, mandatory event taxonomy has proven effective, including market, type of change, time period, source system, and the metric to be checked. Business-critical events should also be defined before go-live. If annotations are only added after a noticeable decline, the risk of incomplete or distorted documentation increases.
Technical implications for larger shops
The API is still documented as a release candidate
Apps can create annotations via the mutation analyticsAnnotationCreate in the Admin GraphQL API.
As of August 3, 2026, Shopify documents this mutation in API version 2026-10. Shopify currently labels this version as a release candidate. The official GraphQL reference lists 2026-07 as the current stable version.
Teams should therefore, before starting productive in-house development, check which API version can be used and whether fields or behavior might still change before the stable release.
The visible merchant function and the technical API version must be considered separately.
Merchants can already see app-generated annotations in the Shopify admin. A new custom integration should still be checked against the actually used API version.
Permissions must be granted separately
Shopify calls the permissions read_analytics_annotations and write_analytics_annotations.
To create, update, and delete an annotation, the app requires write access. For read-only operations, read access is sufficient.
Permissions should only be requested when the app actually needs them.
An app that only writes its own events and updates them later needs a different permission design than an internal analytics tool that is supposed to read annotations from various sources.
Apps may only modify their own annotations
An app can only update or delete annotations that it created itself.
If you try to modify a foreign annotation, Shopify returns a NOT_FOUND error. This applies to both updates and deletions.
This has a direct impact on governance.
A fulfillment app cannot retroactively correct the annotation of a marketing app. Errors must be fixed by the app that was originally responsible.
An event model should be defined before development begins
From a technical standpoint, an annotation can be created quickly. The harder part is deciding when it should be created.
A suitable event model defines at least
- Event type
- Title convention
- Start time
- optional end time
- Description
- affected market
- affected channel
- affected customer group
- source system
- Rule for updating and deleting
- Retention rule
Without these rules, the same event can be created multiple times from different systems.
The external event ID must be stored in the app
The documented input object does not contain its own field for an external ID or URL.
The source system should therefore generate a stable, unique ID for each event. The app stores this ID together with the annotation ID returned by Shopify in its own database.
If the same webhook is received again, the app can update the existing entry instead of creating a second annotation.
This approach prevents duplicate entries and makes rollbacks easier.
Updating and deletion are part of the lifecycle
An integration should not only be able to create new annotations.
She must also take into account that
- the end of a campaign is postponed
- a rollout is canceled
- an event was created twice
- a description needs to be corrected
- a disruption ends sooner or later than expected
Shopify provides mutations for updating and deleting for this purpose.
ShopifyQL is a complementary component
ShopifyQL is the query language behind Shopify Analytics.
Apps can use this to query Shopify data and receive it back in tabular form. To query via the Admin GraphQL API, the read_reports access scope is required. Depending on the customer data being queried, additional requirements for protected customer data may apply.
Shopify is integrating annotations into a broader analytics platform for apps. This also includes ShopifyQL, analyzable metafields, analytics web components, and metric targets.
According to Shopify, App Events are still in early access. However, these additional features are not a prerequisite for understanding and using annotations.
Annotations are no substitute for an external data architecture
Larger companies still need external systems when Shopify data has to be combined with additional information.
These include, for example,
- Purchasing costs
- contribution margins
- full advertising expenses
- Financial accounting
- Call center data
- in-store sales
- Supplier data
- full return costs
The relevant architectural question is
Which operational decisions can be made directly in Shopify, and which require cross-system data?
Multi-store structures require an additional solution
Since annotations are currently not available in multi-store reports, corporate groups with multiple shops need to define their own strategy.
Possible approaches are
- Create events separately in each affected shop
- maintain a central event log outside of Shopify
- perform cross-store analyses in the data warehouse
- use consistent event IDs across all shops
Relevant test cases
Before using it in production, at least these cases should be tested.
- one-time event without an end date
- Event with start and end date
- different time zones
- Switch between daylight saving time and standard time
- Updating an existing event
- Deletion and rollback
- Webhook delivered multiple times
- unsupported event type
- title too long
- description too long
- missing API permission
- reached app limit
- Attempt to modify someone else’s annotation
- Display and filtering in the Shopify admin
- Uninstallation of the generating app
Pre go-live checklist
- Is it defined which decision the annotation is intended to support?
- Only events that could affect relevant key figures are marked
- A Shopify-supported event type is used
- Does the title contain the market, the measure, and, if applicable, the target group
- Are start time, end time, and time zone unambiguous?
- Keep the title under 75 characters and the description under 150 characters
- If the text does not contain any personal data
- Prevents duplicate entries for a stable external event ID
- Can your own annotations be updated and deleted?
- Are reports, key figures, and responsible persons defined before the start?
Summary
- Apps can mark important business events on timelines in Shopify Analytics.
- Shopify shows in the admin which app created an annotation.
- Annotations do not change metrics; they add business context.
- They show temporal relationships but do not prove causation.
- The display only works in reports that include a time dimension.
- Annotations do not appear in report exports and not in multi-store reports.
- Minimum order volume requirements apply to annotations automatically generated by Shopify.
- Merchants currently cannot manually create arbitrary custom annotations in the admin.
- Apps must use an event type supported by Shopify.
- Titles are limited to 75 characters and descriptions to 150 characters.
- An app can only update and delete its own annotations.
- Larger shops need a unified event model, clear responsibilities, and protection against duplicates.
Frequently Asked Questions
What are app annotations in Shopify
App annotations are time-based markers that an installed app places on suitable analytics charts. They show, for example, when a campaign, product launch, or operational change took place.
How much do app annotations cost?
In the official Shopify documentation linked here, no separate additional fee is specified for the display. However, costs may arise from the app used or from developing a custom integration.
Which data is required
For an app-generated annotation, at least one supported event type, a title, and a start time are required. Optionally, a description and an end time can be added.
Can I create annotations myself in the Shopify admin?
No. According to the current Shopify documentation, merchants cannot manually add arbitrary custom annotations. They are created automatically by Shopify or by an app.
Do annotations prove that a campaign has worked?
No. They only show that an event coincided in time with a change. To provide robust evidence of an effect, additional analyses or controlled tests are necessary.
When are annotations unsuitable?
They are unsuitable if every minor change needs to be tracked, if no appropriate time dimension is available, or if complete proof of impact is expected. They also do not replace a project archive or a cross-system data platform.
List of links
Shopify changelog for app-generated annotations
The official dealer announcement explains the fundamental benefits and the visible association with the originating app.
Shopify Help Center on report annotations
The documentation includes prerequisites, supported event types, limitations, and the steps in the Shopify admin.
Shopify developer changelog for app analytics
The technical classification links annotations with ShopifyQL, Analytics Web Components, and metric targets.
Shopify API for creating an annotation
The reference describes the mutation, required permissions, the app limit, and possible errors.
Shopify API for the input object of an annotation
The reference includes required fields and character limits for the title and description.
Shopify API to update an annotation
The documentation explains how an app modifies its own annotations and what limitations apply.
Shopify API for deleting an annotation
The reference describes deleting your own annotations and the error that occurs with entries made by others.
Shopify API to ShopifyQL queries
The documentation explains how to run ShopifyQL via the Admin GraphQL API.
Shopify Help Center on session and consent discrepancies
The page explains how cookie consent can affect session numbers and session-based conversion rates.
