火曜日、売上グラフが落ち込みます。注釈を表示させると、その火曜日にマーカーが1つ立っていて、横に小さなアイコンが並んでいます。月額49ドル払っている会社のロゴです。

マーカーには「キャンペーンが始まった」と書かれています。あなたが置いたものではありません。そもそも、あなたはそこに何も置けません。

これは不具合ではありません。Shopifyがそう設計しています。

5か月前まで、これは閉じた仕組みでした

注釈が公開されたのは2026年5月5日です。当時のマーチャント向けchangelogは、いま動いているものとはかなり違う機能を説明しています。原文を見てください。

Annotations cover three categories today:

• Product events (published, unpublished)
• Store changes (theme published, app installed, app uninstalled)
• System events (data delays, metric definition changes).

6種類です。どれもShopifyが直接観測できる事実に限られています。商品のステータスが変わった、テーマが公開された、アプリがインストールされた。そして記事は次の一文で締められています。「Annotations are generated from your store activity which means no setup & nothing to configure.」

2026年7月21日、shopify.devが同じレイヤーをアプリへ開放しました。その3日後、マーチャント向けchangelogが続きます。「Apps can now add business context directly to your analytics charts with annotations.」

6項目の閉じたリストからオープンなAPIまで、77日でした。

非対称性は、Shopify自身の言葉で書かれています

ヘルプセンターの注釈ページの「considerations」に、この1行があります。

You can't create or add your own annotations manually. Annotations are generated automatically from activity on your store or can be created by apps that you use.

2回読んでください。ストアを運営しているのはあなたです。その火曜日の落ち込みが倉庫のトラブルだったのか、メール配信の失敗だったのか、看板商品が欠品しただけなのか、知っているのはあなたです。しかしShopify管理画面には、それをグラフの横に書き留める欄がありません。

適切な権限を持つアプリには、書けます。

その権限がwrite_analytics_annotationsです。read_ordersやwrite_productsと同じ、インストール時に要求される標準のOAuthアクセススコープです。ドキュメント上、注釈専用の審査ステップも、どのカテゴリーのアプリが要求してよいかという制限も記載されていません。

51種類。そしてアプリ自身の役割は、制限の一つに入っていない

ShopifyQLのANNOTATEリファレンスが全種類の表を公開しており、各タイプがGraphQL Admin APIのどの操作に対応するかという列があります。数えると、9カテゴリー57種類のうち、51種類が「Return, create, update」、つまりアプリが書き込めます。

アプリが作成できない6種類は、ちょうど5月時点のセットと一致します。product_publishedとproduct_unpublished（「Return only」）、そしてapp_installed、app_uninstalled、definition_change、data_unavailable（Admin API上は「Not available」）です。Shopifyは自分で検証できる事実だけを手元に残し、それ以外を開放しました。

その「それ以外」の中身が本題です。以下はすべてアプリが書き込めます。

タイプ	Shopifyによる定義
capital_funding	The business receives funding, such as a Shopify Capital advance or external investment.
team_change	A staffing or leadership change affects operations or customer support.
award_recognition	The business receives an award or industry recognition.
anniversary	The business reaches a brand or founding anniversary.
revenue_milestone	The store reaches a notable revenue threshold or record.
brand_change	The business changes its brand identity, such as its name, logo, or positioning.
attribution_change	Analytics, attribution, or measurement changes affect reported data.
external_event	An external event, such as weather, competitor activity, or an economic change, affects the business.
tax_change	The store changes how it collects taxes or duties.

ドキュメント上、タイプとアプリの機能を結びつける記述はどこにもありません。配送料金アプリがcapital_fundingを書けます。レビューウィジェットがteam_changeを書けます。さらにcustom_events.otherがあり、shopify.devは「an event that doesn't match another supported type」と説明する一方、ヘルプセンターはもう少し踏み込んで「a strategic app moment that no other annotation type covers」と書いています。

Shopify自身が示すユースケースは、与えている権限より狭いものです。開発者向けchangelogより。「Loyalty apps can mark the day a program launched; email apps can mark a new campaign; subscription apps can mark a pricing change.」行儀のよいアプリはそうします。APIはそれを要求していません。

Shopifyが実際にかけた制限

制限は確かに存在しますが、内容ではなく主に分量と長さに関するものです。

タイトルと説明は短い。 AnalyticsAnnotationオブジェクトは、アプリが作成する注釈についてtitleを75文字、descriptionを150文字に制限しています。ここに営業文を書き込める長さではありません。

件数の上限はあるが、数値は公開されていない。 analyticsAnnotationCreateのドキュメントより。

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.

数値はドキュメントのどこにも書かれていません。そして交渉できるのはアプリ開発者であって、あなたではありません。1つのアプリがグラフをどこまで占有できるかの実質的な上限は、調べることも設定することもできない数字です。

出所の表示は強制される。 すべての注釈はsourceフィールド（APPまたはSHOPIFY）を持ち、アプリ作成分はcreatedByAppにアプリのIDとタイトルを持ちます。ヘルプセンターもUI上での表示を明記しています。「Activities generated by apps display the icon and name of the app that generated the event.」誰が書いたかは常に分かります。

アプリ同士は上書きできない。 analyticsAnnotationUpdateは、自分が作成していない注釈を変更しようとするとNOT_FOUNDを返します。ただしこれは両刃です。あるアプリが残した誤りを、別のアプリがあなたの代わりに片付けることもできません。

数値そのものは変わらない。 マーチャント向けchangelogの2本はほぼ同じ表現でこう書いています。「Annotations don't change your report data. They add context to help you understand what might have influenced trends or changes.」これはデータ層ではなく、キャプション層です。

望まない注釈に対して、実際にできること

ヘルプセンターが記載しているマーチャント側の操作は3つで、いずれも表示上のものです。

• マーカーの表示・非表示を切り替える。注釈は既定で非表示で、VisualizationメニューのShow annotations、または注釈パネルから有効にします。
• アクティビティタイプで絞り込む。選択内容はレポートと一緒に保存されます。
• キーワードで注釈を検索する。

マーチャントが管理画面からアプリ作成の注釈を削除する方法は、どこにも記載されていません。analyticsAnnotationDeleteは存在しますが、これはAPI操作であり、アプリは自分が作ったものしか削除できません。あるアプリが誤った内容を書き込んだまま保守をやめた場合、記載されている対処は、注釈レイヤーごとオフにするか、そのタイプを全アプリ分まとめて除外するか、アンインストールするかです。

運用に組み込む前に知っておきたい制約もいくつかあります。注釈はレポートのエクスポートに含まれません。マルチストアレポートとcohorts methodでは使えません。時間軸が必要なため、ドーナツチャート、テーブル、コホートグリッドには何も出ません。そして注釈パネルはアクティビティタイプごとに一度に最大10件まで、business impact順で表示します。イベントの多い日に見えているのは抜粋であって、全件ではありません。

店舗が小さいほど、グラフはアプリのものになる

ここが最も見落とされやすい部分です。Shopify生成の注釈には、同じconsiderationsリストの中に条件が書かれています。

• You average 10 or more orders per week for at least 12 non-consecutive weeks within the past 6 months.
• You've received at least 1 order in the past 2 weeks.

この基準を下回ると、Shopifyは何も書きません。当初の機能そのものだった商品公開・テーマ公開・アプリインストールが、そもそも表示されません。

一方、アプリ作成の注釈にこうした条件はドキュメント上ありません。つまり週5件の注文の店舗では、注釈タイムラインのマーカーがすべて第三者由来になり、比較対象となるShopify検証済みイベントの土台がありません。機能の意味が反転します。自分のストアが何をしたかを見せるために作られたものが、小規模店ではベンダーが何をしたと主張しているかだけを見せる仕組みになります。

分析画面へのもう一つの経路と、すでにそちらを選んだアプリ

注釈は7月に出荷されたものの、目に見える半分です。静かなもう半分がanalyticsQueryableというメタフィールドのcapabilityで、アプリのメタフィールドをShopifyQLでグループ化・絞り込みできるディメンションに変えます。管理画面ではUse in analyticsというスイッチとして現れます。

これを理解しておく価値があるのは、取引の性質が正反対だからです。注釈は、アプリがあなたのビジネスについて行う主張です。クエリ可能なメタフィールドは、アプリが集めたデータをあなた自身の注文レコードや顧客レコードに載せたもので、切り口はあなたが決められます。

Fairing Post Purchase Surveysは2026年4月2日、注釈APIが存在するより前にこちらの経路を実装しました。そしてShopifyはSpring '26の分析機能紹介記事でこのアプリを実名で挙げています。

出典: Shopify App Store（Fairing Post Purchase Surveys、2026-09-16時点）

Fairingは購入後アンケートの回答、つまり「how did you hear about us?」への答えを、注文オブジェクトのメタフィールドとして書き込みます。同社の連携に関する記事は理由についてかなり率直です。「We made a deliberate choice not to build this reporting in-house.」そして「We're not building a BI tool. We're not trying to become your reporting platform.」

同じ記事から仕組みを拾うと、必要なスコープはwrite_orders、設定は約5分、過去データは既定でバックフィルされ、無効にする選択肢もあり、保存される値はShopifyの標準的なメタフィールド上限に従います。App Storeのリスティングでは評価5.0、レビュー195件、200件の注文までFreeプラン、201〜500件で$49/month、1,000件までで$99/month、5,000件までで$149/month、有料プランは14日間の無料トライアル付きです。リスティングにBuilt for Shopifyバッジはありません。

この連携が要求しているスコープに注目してください。アンケート回答を注文に書き込むにはwrite_ordersが必要で、これはあなたが精査するはずの権限です。売上グラフに主張を書き込むために必要なのはwrite_analytics_annotationsで、こちらは名前すら聞いたことがないマーチャントがほとんどです。

対応範囲にずれもあります。Shopifyの開発者向けドキュメントはanalyticsQueryableをcustomer、order、product、product variantのメタフィールド定義に適用されるとし、すべてのメタフィールドタイプが対象ではないと書いています。一方ヘルプセンターのマーチャント向けページは、レポートでのメタフィールド対応をProducts、Variants、Customers、Orders、Transfers、Locationsとして挙げています。2つのリストは一致しません。特定のオブジェクトがレポート上で重要なら、どちらのページも鵜呑みにせず、自分の管理画面で確認してください。

ここから何をするか

3つ、順番に。

一度注釈を表示させて、すべてのマーカーの出所を見る。 既定でオフなので、多くのストアは自分のグラフに何が書き込まれているかを見たことがありません。注釈パネルにアプリのアイコンと名前が表示されます。そのアプリの機能と関係のないタイプ、たとえば配送アプリからのrevenue_milestone、分析ツールでないものからのattribution_changeを見つけたら、開発元に問い合わせる価値があります。

インストール時にwrite_analytics_annotationsを本物の権限として扱う。 これはデータアクセス系のスコープではないため、通常のプライバシー確認の話題に上がりません。しかしベンダーが自社ロゴ付きのテキストを、あなたが意思決定に使う数値の横に置けるようになります。何を、どの頻度で書き込むのか確認してください。

注釈が残り続ける前提でレポート運用を組まない。 エクスポートには含まれず、アプリごとの件数上限は非公開で、削除できるのは作成したアプリだけで、時間軸のないチャートには表示されません。「その週に何があったか」を思い出すきっかけとしては有用です。記録としては、あなたのものではありません。

率直にまとめると、Shopifyはコンテキスト層を作り、プラットフォームが外側からビジネスについて観測できる限界に突き当たり、その先をマーチャントではなくアプリへ委ねました。この構図の中で、自分のグラフへの書き込み権限を持たない唯一の当事者がマーチャントです。

出典

• Full-stack capabilities to power app analytics — Shopify developer changelog、2026年7月21日
• Analytics — shopify.dev
• analyticsAnnotationCreate、AnalyticsAnnotation — GraphQL Admin API 2026-10
• ANNOTATE — ShopifyQL syntax reference
• Use metafield capabilities — shopify.dev
• Annotations in your Shopify reports — Shopifyヘルプセンター
• Filtering and editing your reports — Shopifyヘルプセンター
• Annotations bring store event context directly to your analytics — Shopify Changelog、2026年5月5日
• New app-added annotations on your analytics charts — Shopify Changelog、2026年7月24日
• Better Context for Your Store's Data: 5 Updates to Analytics in Shopify — Shopifyブログ、2026年6月17日
• Fairing Data Now Lives in Shopify Analytics — Fairing、2026年4月2日
• Fairing Post Purchase Surveys — Shopify App Store、2026-09-16時点