Annotations

An annotation is a note pinned to a date that shows on your charts, so a spike or a drop comes with its reason. Mark a sale, a launch or a site outage, for example. Annotations are shared, so everyone on your team sees the same ones.

How It Works

Where Annotations Show

Each annotation appears as a vertical line on report charts that show change over time, and on the same charts on your dashboards. The Advertising page shows it on its ad charts.

The label sits at the top of the line, shortened when it’s long. Hover over it to see the full label, the date, the description and who or what made it.

When annotations fall on the same or nearby dates, each keeps its line but they share one marker with a count, such as 3. Hover over the count to see each one’s label and date. Click it to choose one to open.

A label with no room beside its neighbors shows as a dot.

When a chart groups days into weeks or months, the line sits on the week or month that contains the date. Pages with their own layout, such as P&L and Pulse, don’t show annotations.

Which notes a chart shows depends on what the chart is about:

• A note a teammate made shows on every chart. That includes notes you type, Copilot drafts, notes added over MCP and recorded decisions.
• A note By the Numbers adds on its own shows on charts about its subject: ads, email, customers, products or subscriptions. A spend change is about ads, so it shows on the Advertising page, on Campaign Performance and on the Web Analytics reports.
• Every chart in the Sales and Profitability reports shows every note.

Adding an Annotation

You can add one from a chart or from the Annotations page:

• From a chart: choose the Add annotation icon at the top of a report’s chart. The date starts as the first day of the report’s date range.
• From the Annotations page: open Annotations, under Settings in the navigation, and choose Add Annotation. When you have none yet, the button is Add your first annotation.

Either way, fill in:

• Label: a short title shown on the chart, up to 120 characters. For example, Black Friday Sale.
• Date: the single day it happened. There’s no end date, so for an event over several days, add one annotation per day or mark the day it started.
• Description (optional): more detail, shown when someone hovers over the line.

Choose Add to save it. It appears on every over-time chart whose date range includes that day.

Tell Copilot what happened and on which date, then choose Add Annotation under its draft. An assistant connected over MCP can add one with its create_annotation tool. Either way, the note is saved under your name.

Recording a Campaign Decision

On the Advertising page, each row of the campaign table has Record This Decision. It opens the same dialog, dated today, with the label “Decision: “ and the campaign’s name.

When the campaign has figures, such as its reported ROAS, the description lists them. It ends with a colon, for you to write what you decided.

From then on, the decision shows on your charts at that date, so you can see what happened after it. On the Advertising page it shows on the Ad Spend and CPC charts. This option is in beta.

The decision also remembers the campaign and its figure. Open it from a chart to see the 7 days before and after. The week after appears once it has fully passed.

With das Pixel measuring, you see spend, measured revenue and measured ROAS. These come from the last paid click, and 7 days is short for a store whose customers take longer than a week to buy.

Without das Pixel, or for days before you installed it, you see spend and the platform’s own reported ROAS. Below them are your whole store’s net sales, orders, new customers and average order value. These count every order, not only orders from that platform’s ads.

Neither set of figures shows that the change caused the difference.

Spend Changes Added for You

When you have an ad platform connected, By the Numbers adds an annotation when a platform’s or campaign’s daily spend moves to a new level and holds. It sits on the day the new level started. Its label reads like “Prospecting (Meta Ads) daily spend down 40%”.

The new level has to be at least 25% above or below the typical day of the 14 days before. It also has to hold for at least 5 of the next 7 days. So the annotation appears about a week after the change.

Small moves in small campaigns don’t count, and at most 5 appear a day.

Open one from a chart to see the 7 days before and after, with the same figures as for a decision. It only records the move and doesn’t say whether it was right. If you delete one, By the Numbers doesn’t add it again.

Other Notes Added for You

By the Numbers also adds a note when your data shows an event a chart can’t explain. Each note says what happened in plain numbers and gives no advice. It sits on the day the event started, in your store’s time zone.

It adds at most 5 notes a day, spend changes included. A note you delete is never added again. Notes from orders leave out canceled, voided and expired orders.

Each kind also shows on every chart in the Sales and Profitability reports. The lines below name the other charts it shows on. The Web Analytics reports show both ad and email notes.

Ad charts are the charts about ad spend, such as the Advertising page and Campaign Performance. Email charts include Klaviyo Performance. Customer, product and subscription charts are the reports about those subjects.

• Klaviyo Sends: a sent campaign that reached at least 1,000 people and at least 1.5 times your usual send on its channel, email or text. Your usual send is the median send on that channel in the 90 days before, and it needs at least 5 sends in that time. A send is skipped when one in the 14 days before reached 80% of its size. One note a day, for the largest send. Example: “Klaviyo email to 47,658 people: Black Friday Early Access”. It shows on email charts.
• Segment Syncs: each day you start syncing segments, one note names the segments and where they went. A segment that already synced to the same platform in the 30 days before doesn’t count. A Money Moves Send from Pulse counts. Examples: “Started syncing Active Subscribers to Google Ads and Klaviyo” and “Sent the Money Moves group Lapsed VIPs to Klaviyo”. It shows on customer and email charts, and on ad charts when a platform is an ad platform.
• Integration Disconnects: an integration a teammate disconnected and didn’t connect again within 24 hours. The note is dated the day it was disconnected and added once the 24 hours have passed. Google Drive and Dropbox are left out, and a connection that breaks on its own isn’t a disconnect. The label says what it did to your charts. Example: “Meta Ads disconnected. Its ad spend was removed from your charts.” It shows on ad charts for an ad platform or Shop Campaigns, and on email charts for Klaviyo, Mailchimp or Attentive. A Google Analytics note shows only on the Sales and Profitability reports.
• Discount Code Starts: a code not used in the 90 days before. It starts on the first day it’s on 3 or more orders, within 30 days of its first use. It’s noted when its first 7 days have at least 20 orders and at least 10% of your orders. One note a day, for the code with the most orders, added a week after it started. Example: “Discount code WELCOME15 started: 1,240 orders in its first 7 days”. It shows on product and customer charts.
• Large Orders: a day’s largest order, when it’s at least 1,000 US dollars and at least 10 times your usual order. It also has to be at least a usual day of sales and 1.5 times the largest order of the 28 days before. Your usual order is the median of the daily median orders in those 28 days, and a usual day is the median day. Example: “Order #1042 for 151,750: as much as 27 usual days of sales”. It shows only on the Sales and Profitability reports.
• Product Launches: a product’s first sale, with none in the 90 days before, when the product was published or created at most 30 days earlier. It’s noted when its first 14 days of sales are at least 10% of your sales and at least 500 US dollars. Gift cards are left out. One note a day, for the product with the most sales, with “and 2 more” when several launched. Example: “New product Mandarin Soda: 43% of sales in its first 14 days”. It’s added 2 weeks after the first sale and shows on product charts.
• New Sales Channels: the first orders from an app with none in the 90 days before. Its first 14 days need at least 10 orders and at least 2% of your sales, and your store needs orders on 20 of the 28 days before. Example: “First orders from Wholesale Portal: 12% of sales in 14 days”. Past half your sales it reads “Orders moved to Checkout Plus: 88% of sales in its first 14 days”. It’s added 2 weeks after the first order and shows only on the Sales and Profitability reports, plus subscription charts for a subscription app.
• Refund Spikes: the refunds processed on a day, when they come to at least 500 US dollars. They must also be at least 5 times a usual refund day and at least half a usual day of sales. A usual day is the median of the 28 days before. The day also has to beat every refund day in those 28 days, with refunds on at least 5 orders unless one refund is half of the total. At most one note in 7 days. Example: “Refunds on 375 orders in one day, 26 times a usual day”. It names the most refunded product when that product has a third of the refunded units. It shows only on the Sales and Profitability reports, because the sales line dips on the day a refund is processed.
• First Subscription Orders: your store’s first day with an order on a subscription plan, with none in the 90 days before. Pre-order plans don’t count. It’s noted when its first 14 days bring at least 10 new subscribers, and your store had orders on 20 of the 28 days before. Example: “First subscription orders: 104 new subscribers in 14 days”. It’s added 2 weeks after the first order and shows on subscription charts.

Who or What Made an Annotation

Every annotation says who or what made it. The line shows when you hover over a note on a chart, at the top of its edit dialog and in the Source column on the Annotations page.

It reads one of these ways:

• “Added by Sam Lee”: typed in by Sam. Notes added before By the Numbers recorded sources all read this way.
• “Drafted by Copilot, added by Sam Lee”: a Copilot draft that Sam added.
• “Added by Claude (MCP) for Sam Lee”: added by an AI assistant over MCP, with Sam’s connection. The line names the app only when the app registered a name. Otherwise it reads “Added through MCP for Sam Lee”.
• “Decision recorded by Sam Lee”: recorded with Record This Decision.
• “Detected from Meta Ads spend”: a spend change. It names the ad platform.
• “Detected from Klaviyo”: a Klaviyo send.
• “Detected from your segment syncs”: a segment sync.
• “Detected from your integrations”: an integration disconnect.
• “Detected from your orders”: a discount code start, a large order, a product launch, a new sales channel or first subscription orders.
• “Detected from your refunds”: a refund spike.

When a teammate’s account is gone, their name reads “a former team member”.

The Source filter above the list shows one kind of note at a time, such as Campaign Decisions or Klaviyo Sends. It lists only the kinds your store has. Choose All Sources to see every note.

Turning Off Automatic Notes

The Added Automatically card, below the list on the Annotations page, has a switch for each kind of note By the Numbers adds on its own. Each switch is named for the kind, such as Large Orders.

Turn a switch off and that kind of note leaves every chart. Its notes stay in the list. Turn the switch on again and they return to the charts.

Anyone on your team can see the switches. Changing one needs the Edit dashboards permission.

Editing and Deleting

Select an annotation’s line on a chart, or its edit icon on the Annotations page, to change it. To delete it, choose Delete in the edit dialog or the delete icon on the Annotations page.

A deleted annotation leaves every chart at once. The message that follows has Undo.

Undo adds the note back as a new one. A recorded decision keeps its figures and a Copilot draft stays a Copilot draft. Any other note, including one added over MCP, comes back as a note you added.

Anyone on your team can add an annotation. You can edit or delete your own. People with the Edit dashboards permission can edit or delete anyone’s.

A note By the Numbers adds on its own has no author. Only people with that permission can change it.

Every annotation a teammate adds, changes or deletes is listed in the Audit Log, and so is every change to the switches.

Notes By the Numbers adds on its own aren’t listed, and neither is deleting one.

What It Means for You

Add an annotation whenever you do something that could move the numbers: a promotion, a price change, a new ad campaign, an email to your whole list, or a stockout. When someone looks at the chart later, the reason is already there.

Annotations are most useful when the whole team adds them. Agree on short, plain labels, so the lines are easy to read on a busy chart.

Related

• Annotations: every annotation in one list, by date.
• Dashboards: where annotations also show on your cards.