diff --git a/MIGRATION.md b/MIGRATION.md
index f81bfba39c2..e849e52ec06 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -9,6 +9,7 @@
     - [Behavioral differences](#behavioral-differences)
     - [Using the v7 store](#using-the-v7-store)
     - [V7-style story sort](#v7-style-story-sort)
+    - [Store API changes for addon authors](#store-api-changes-for-addon-authors)
   - [Babel mode v7](#babel-mode-v7)
   - [Loader behavior with args changes](#loader-behavior-with-args-changes)
   - [Angular component parameter removed](#angular-component-parameter-removed)
@@ -332,6 +333,14 @@ function storySort(a, b) {
 },
 ```
 
+#### Store API changes for addon authors
+
+The Story Store in v7 mode is async, so syncronous story loading APIs no longer work. In particular:
+
+ - `store.fromId()` has been replaced by `store.loadStory()`, which is async (i.e. returns a `Promise` you will need to await).
+ - `store.raw()/store.extract()` and friends that list all stories require a prior call to `store.cacheAllCSFFiles()` (which is async). This will load all stories, and isn't generally a good idea in an addon, as it will force the whole store to load.
+
+
 ### Babel mode v7
 
 SB6.4 introduces an opt-in feature flag, `features.babelModeV7`, that reworks the way Babel is configured in Storybook to make it more consistent with the Babel is configured in your app. This breaking change will become the default in SB 7.0, but we encourage you to migrate today.