diff --git a/doc/Upgrade notes.md b/doc/Upgrade notes.md
index 8ab91583e3..c167e3a112 100644
--- a/doc/Upgrade notes.md	
+++ b/doc/Upgrade notes.md	
@@ -2,6 +2,67 @@
 
 We're trying to keep the upgrade process as easy as it's possible. Unfortunately sometimes manual code changes are required. Before pulling out the latest version, please take a look at the upgrade notes below:.
 
+## 1.0RC-2 -> 1.0RC-3 ([release notes](https://github.com/DivanteLtd/vue-storefront/releases/tag/v1.0.0-rc.3))
+This release contains three important refactoring efforts:
+
+1. We've changed the user-account endpoints and added the token-reneval mechanism which is configured by `config.users.autoRefreshTokens`; if set to true and user token will expire - VS will try to refresh it.
+
+2. Moreover we've separated the user-account entpoints - so please copy the following defaults from `default.json` to Your `local.json` and set the correct api endpoints:
+
+```json
+    "users": {
+      "autoRefreshTokens": true,
+      "endpoint": "http://localhost:8080/api/user",
+      "history_endpoint": "http://localhost:8080/api/user/order-history?token={{token}}",
+      "resetPassword_endpoint": "http://localhost:8080/api/user/resetPassword",
+      "changePassword_endpoint": "http://localhost:8080/api/user/changePassword?token={{token}}",
+      "login_endpoint": "http://localhost:8080/api/user/login",
+      "create_endpoint": "http://localhost:8080/api/user/create",
+      "me_endpoint": "http://localhost:8080/api/user/me?token={{token}}",
+      "refresh_endpoint": "http://localhost:8080/api/user/refresh"
+    },
+```
+
+The endpoints are also set by the `yarn installer` so You can try to reinstall VS using this command.
+
+3. We've optimized the performance by limiting the fields loaded each time in JSON objects from the backend. Please review the `config/default.json` and if some required / used by Your app fields are missing there - please copy the following fragment to the `config/local.json` and add the required fields:
+
+```json
+    "entities": {
+      "optimize": true,
+      "twoStageCaching": true,
+      "category": {
+        "includeFields": [ "children_data", "id", "children_count", "sku", "name", "is_active", "parent_id", "level" ]
+      },
+      "attribute": {
+        "includeFields": [ "attribute_code", "id", "entity_type_id", "options", "default_value", "is_user_defined", "frontend_label", "attribute_id", "default_frontend_label", "is_visible_on_front", "is_visible", "is_comparable" ]
+      },
+      "productList": {
+        "includeFields": [ "type_id", "sku", "name", "price", "priceInclTax", "originalPriceInclTax", "id", "image", "sale", "new" ],
+        "excludeFields": [ "configurable_children", "description", "configurable_options", "sgn", "tax_class_id" ]
+      },
+      "productListWithChildren": {
+        "includeFields": [ "type_id", "sku", "name", "price", "priceInclTax", "originalPriceInclTax", "id", "image", "sale", "new", "configurable_children.image", "configurable_children.sku", "configurable_children.price", "configurable_children.special_price", "configurable_children.priceInclTax", "configurable_children.specialPriceInclTax", "configurable_children.originalPrice", "configurable_children.originalPriceInclTax", "configurable_children.color", "configurable_children.size" ],
+        "excludeFields": [ "description", "sgn", "tax_class_id" ]
+      },
+      "product": {
+        "excludeFields": [ "updated_at", "created_at", "attribute_set_id", "status", "visibility", "tier_prices", "options_container", "url_key", "msrp_display_actual_price_type", "has_options", "stock.manage_stock", "stock.use_config_min_qty", "stock.use_config_notify_stock_qty", "stock.stock_id",  "stock.use_config_backorders", "stock.use_config_enable_qty_inc", "stock.enable_qty_increments", "stock.use_config_manage_stock", "stock.use_config_min_sale_qty", "stock.notify_stock_qty", "stock.use_config_max_sale_qty", "stock.use_config_max_sale_qty", "stock.qty_increments", "small_image"],
+        "includeFields": null
+      }
+    },
+```
+
+If `optimize` is set to false - it's a fallback to the previous behaviour (getting all fields).
+
+4. Another cool feature is `twoStageCaching` enabled by default. It means that for the Category page VS is getting only the minimum number of JSON fields required to display the ProductTiles and shortly after it downloads by the second request the full objects to store them im local cache.
+
+5. We've tweaked the Service Worker to better cache the app - it sometimes can generate kind of frustration if your home page is now cached in the SW (previously was not). Feel free to use `Clear Storage` in Your Developers tools :)
+
+6. The `mage2vuestorefront` tool got update and now it's loading the `media_gallery` with additional media per product. We've also put some MediaGallery component on the product page.
+
+7. Product and Category pages got refactored - and it's a massive refactoring moving all the logic to the Vuex stores. So If You played with the core - `fetchData`/`loadData` functions probably Your code will be affected by this change.
+
+
 ## 1.0RC -> 1.0RC-2 ([release notes](https://github.com/DivanteLtd/vue-storefront/releases/tag/v1.0.0-rc.2))
 This release brings some cool new features (Magento 1.x support, Magento 2 external checkout, My Orders, Discount codes) together with some minor refactors.