shopware · Su (sushmangupta) · Mar 2, 2026 · Feb 24, 2026 · Feb 24, 2026 · Feb 24, 2026
diff --git a/concepts/api/admin-api.md b/concepts/api/admin-api.md
diff --git a/concepts/api/index.md b/concepts/api/index.md
diff --git a/concepts/api/store-api.md b/concepts/api/store-api.md
diff --git a/concepts/apis/index.md b/concepts/apis/index.md
@@ -0,0 +1,50 @@
+---
+nav:
+  title: APIs
+  position: 40
+
+---
+
+# APIs
+
+Shopware exposes HTTP-based APIs that allow external systems and custom applications to interact with the platform.
+
+Two functional APIs are available, each representing a different integration surface:
+
+* **Store API**: customer-facing interactions
+* **Admin API**: administrative and system-level operations
+
+Both APIs use HTTP, exchange structured JSON payloads, and require authenticated access. While they serve different purposes within the platform, they share some underlying design principles and structural patterns:
+
+* Search criteria abstraction for filtering, sorting, and pagination
+* Structured JSON request/response bodies
+* Versioned endpoints
+* Header-based contextual behavior
+
+These patterns form the foundation of integration development.
+
+## Store API
+
+The Store API represents the customer-facing surface of Shopware. It is designed for storefront/frontend-related interactions such as product browsing, cart handling, checkout, and customer account management. It exposes only data that is relevant and safe for frontend use and supports both anonymous and authenticated customers.
+
+The Store API acts as a normalized interface layer between customer-facing applications and the Shopware Core. It enables headless frontends (such as SPAs or native apps) to consume Shopware functionality via JSON over HTTP. Core business logic is exposed through HTTP routes, ensuring that the Storefront and API consumers rely on the same underlying services.
+
+Authoritative endpoint documentation:
+
+<PageRef page="https://shopware.stoplight.io/docs/store-api/7b972a75a8d8d-shopware-store-api" title="Store API – Stoplight Reference" target="_blank" />
+
+* An interesting project based on the Store API is [Composable Frontends](../../../frontends/).
+
+## Admin API
+
+The Admin API represents the administrative and integration surface of Shopware. It enables structured access to core business entities such as products, orders, customers, media, and configurations. It is intended for backend integrations, automation, data synchronization, and system-to-system communication.
+
+These integrations typically involve structured data exchange, synchronization, imports, exports, and notifications. They prioritize consistency, error handling, validation, and transactional integrity. Performance is also important in terms of high data loads rather than fast response times.
+
+The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems.
+
+Authoritative endpoint documentation:
+
+<PageRef page="https://shopware.stoplight.io/docs/admin-api/8d53c59b2e6bc-shopware-admin-api" title="Admin API – Stoplight Reference" target="_blank" />
+
+For details on endpoints, authentication methods (including token-based authentication and OAuth 2.0), schemas, and request formats, always refer to the Stoplight documentation.
diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md
@@ -32,7 +32,23 @@ The main concerns that the Storefront component has are listed below. Furthermor
 
 Contrary to API calls that result in single resource data, a whole page in the Storefront displays multiple different data sets on a single page. Think of partials, which lead to a single page being displayed. Imagine a page that displays the order overview in the customer account environment. There are partials that are generic and will be displayed on almost every Page. These partials include - for example, Header and Footer information wrapped into a `GenericPage` as `Pagelets` \(`HeaderPagelet`, `FooterPagelet`\). This very generic Page will later be enriched with the specific information you want to display through a separate loader \(e.g. a list of orders\).
 
-To achieve getting information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront makes use of the [Store API](../../api/store-api) routes to enrich the Page with additional information, e.g., a list of orders, which is being fetched through the order route. Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller.
+To obtain information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront makes use of the [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) routes to enrich the Page with additional information, e.g., a list of orders, which is being fetched through the order route.
+
+![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../assets/concepts-api-storeApiLogic.svg)
+
+Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller.
+
+### Store API and the traditional TWIG storefront
+
+In the traditional server-side rendered Twig storefront, the Store API is not called directly by the browser. Instead, custom storefront controllers internally use the Store API to fetch data from the Core.
+
+The Store API is stateless and expects authentication information via request headers (for example the `sw-context-token`). In contrast, the traditional storefront relies on session-based authentication, so authentication does not need to be handled manually on every request.
+
+### Store API and the traditional Twig storefront
+
+In the traditional server-side rendered Twig storefront, the Store API is not called directly by the browser. Instead, custom storefront controllers internally use the Store API to fetch data from the Core.
+
+The Store API is stateless and expects authentication information via request headers (for example the `sw-context-token`). In contrast, the traditional storefront relies on session-based authentication, so authentication does not need to be handled manually on every request.
 
 Contrary to the Core, which can almost completely omit templating in favor of JSON responses, the Storefront contains a rich set of Twig templates to display a fully functional shop. Another concern of the Storefront is to provide templating with Twig. The page object, which was enriched beforehand, will later be passed to a specific Twig page template throughout a controller. A more detailed look into an example can be found in [Composite data handling](storefront-concept#composite-data-handling).
 

diff --git a/guides/upgrades-migrations/administration/index.md b/guides/upgrades-migrations/administration/index.md
@@ -0,0 +1,17 @@
+---
+nav:
+  title: Administration
+  position: 10
+
+---
+
+# Administration
+
+These guides cover upcoming architectural changes and migration paths affecting Administration extensions. Use them to prepare plugins for major system transitions:
+
+* [Vue 3 migration](./vue3)
+* [Meteor components](./meteor-components)
+* [Pinia migration](./pinia)
+* [Vite migration](./vite)
+* [Vue migration build removal](./vue-migration-build)
+* [Native Vue implementation](./vue-native)
diff --git a/...ation/system-updates/meteor-components.md → ...tions/administration/meteor-components.md b/...ation/system-updates/meteor-components.md → ...tions/administration/meteor-components.md
diff --git a/...ns/administration/system-updates/pinia.md → ...grades-migrations/administration/pinia.md b/...ns/administration/system-updates/pinia.md → ...grades-migrations/administration/pinia.md
diff --git a/...ins/administration/system-updates/vite.md → ...pgrades-migrations/administration/vite.md b/...ins/administration/system-updates/vite.md → ...pgrades-migrations/administration/vite.md
diff --git a/...ion/system-updates/vue-migration-build.md → ...ons/administration/vue-migration-build.md b/...ion/system-updates/vue-migration-build.md → ...ons/administration/vue-migration-build.md
diff --git a/...ministration/system-updates/vue-native.md → ...s-migrations/administration/vue-native.md b/...ministration/system-updates/vue-native.md → ...s-migrations/administration/vue-native.md
diff --git a/...eferences/upgrades/administration/vue3.md → ...pgrades-migrations/administration/vue3.md b/...eferences/upgrades/administration/vue3.md → ...pgrades-migrations/administration/vue3.md
@@ -5,7 +5,7 @@ nav:
 
 ---
 
-# Vue 3 upgrade
+# Vue 3 Upgrade
 
 ## Introduction
 

diff --git a/...core/translation/extension-translation.md → ...rades-migrations/extension-translation.md b/...core/translation/extension-translation.md → ...rades-migrations/extension-translation.md
@@ -23,10 +23,10 @@ The snippet loading system now follows this resolution order:
 
 When a translation key is requested, Shopware will:
 
-- First check the specific country variant (e.g., `es-AR`)
-- If not found, check the base language (e.g., `es`)
-- If not found, the legacy fallback will be checked (`en-GB`)
-- Finally, fall back to `en` if still not found
+* First check the specific country variant (e.g., `es-AR`)
+* If not found, check the base language (e.g., `es`)
+* If not found, the legacy fallback will be checked (`en-GB`)
+* Finally, fall back to `en` if still not found
 
 **Result**: ~90% reduction in duplicate translations while maintaining full functionality.
 

diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md
@@ -0,0 +1,80 @@
+---
+nav:
+  title: Upgrades and Migrations
+  position: 10
+
+---
+
+# Version Upgrades and Migrations
+
+This section covers version-based upgrades and required migration effort for Shopware core and extensions. When upgrading to a new minor or major Shopware version, review it to understand breaking changes, required adjustments, and compatibility requirements.
+
+## Scope of this section
+
+Upgrades typically fall into one of these categories:
+
+* **Core**: Framework-level changes, data abstraction layer (DAL) updates, APIs, feature removals, and backend behavior.
+* **[Administration](administration/index.md)**: frontend framework upgrades, Vue upgrades, breaking changes.
+* **Translations**: [Extension translation](extension-translation), [Language pack migration](./language-pack-migration).
+* **Extensions**: Version compatibility and required refactorings.
+
+:::info
+Administration upgrades (Vue, Pinia, Vite, Meteor) may require major plugin version bumps.
+:::
+
+## Upgrade strategy for extension developers
+
+To reduce long-term upgrade cost:
+
+* Avoid internal APIs and undocumented features
+* Avoid unstable Admin patterns (`this.$parent`, prop mutation, Vue internals)
+* Keep dependencies aligned with Shopware core
+* Maintain automated test coverage
+* Keep database migrations idempotent
+* Track deprecations continuously—do not batch them
+
+For general development best practices that reduce upgrade friction, see the [Development guide](../development/index.md).
+
+## Typical upgrade workflow
+
+When targeting a new Shopware version:
+
+1. Review [release notes](https://www.shopware.com/de/changelog/) and UPGRADE files
+2. Check breaking changes per layer (Core / Admin / Translations)
+3. Validate extension compatibility
+4. Apply required migrations
+5. Rebuild Admin/Storefront assets if needed
+6. Test critical flows
+7. Update extension versions if required
+
+## Extension responsibilities
+
+### Custom projects
+
+* Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order.
+* Review changelogs/UPGRADE files per release.
+* Script data migrations and cache warm-ups.
+* Use feature toggles or maintenance mode to decouple risky changes from the deploy moment.
+
+### Custom plugins
+
+* Provide migration code for schema/config changes.
+* Ship defaults that work on older core versions until you deliberately drop support.
+* Test against the target Shopware version matrix before rollout; note breaking changes in the plugin README.
+
+### Store plugins
+
+* Align Store metadata (compatibility range, changelog) with the tested core versions; refuse installation on unsupported versions.
+* Run Shopware Store validation on the new build before submission ([Store submission via CLI](../../products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md)).
+* Communicate BC breaks explicitly.
+* Prefer additive changes and feature flags to keep existing shops stable.
+
+### Apps
+
+* Version manifests carefully. Broaden compatibility only after testing, and narrow it when deprecations apply.
+* Keep webhook/action handlers tolerant to new fields and events. Avoid hard coupling to specific core patch behavior.
+* Document required scopes/permissions per version and avoid removing scopes without a migration path.
+
+## Next steps
+
+For the operational update procedure, continue with [Update Shopware](update-shopware).
diff --git a/...re/translation/language-pack-migration.md → ...des-migrations/language-pack-migration.md b/...re/translation/language-pack-migration.md → ...des-migrations/language-pack-migration.md
@@ -39,7 +39,7 @@ Starting with Shopware **6.7.3.0**, translations are managed directly in Shopwar
 - Nothing changes.
 - To install additional languages, use the CLI command:
 
-```bash
+```bash  
   bin/console translation:install --locales <locale-code>
 ```
 
@@ -55,16 +55,10 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It
 
 2. The command uses the **same source ([translate.shopware.com][shopware-translations])** as the [Language Pack plugin][language-pack-plugin] but is
    updated more frequently. So it's essentially identical – or even more up to date!
-3. Make sure that all languages you need are **active** in the Administration: `Settings → Languages`
-4. Create base snippet sets for used languages
-   - If you're on Shopware **6.7.7.0** or later, this is done automatically.
-   - If you're on Shopware **6.7.6.0** or earlier, for each language in use, create a base snippet, e.g. `BASE en-US` for English (US).
-5. Change all sales channel domains to use the base snippet sets.
-   - If you're on Language Pack **5.37.1** or later, this is done automatically.
-   - If you're on Language Pack **5.37.0** or earlier, open each sales channel, scroll down to the domains and change the
-     snippet set from `LanguagePack` to `BASE`, e.g.: `LanguagePack en-US` to `BASE en-US`.
-6. It is recommended to uninstall and remove the Language Pack plugin after `translation:install` succeeded for all locales.
-   Your **custom snippets** created in the snippet module remain intact since they are saved in the database.
+3. You can safely uninstall and remove the Language Pack plugin. Your **custom snippets** created in the Snippet module
+   remain intact since they are saved in the database.
+4. Make sure that all languages you need are **active** in the Administration:
+   `Settings → Languages`
 
 ## New installations
 
@@ -76,14 +70,6 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It
 
 - Additional details about the new translation handling are available in the [integrated language handling][translation-system] guide.
 
-## Common problems and troubleshooting
-
-### Can't remove Language Pack: a foreign key constraint fails (\`shopware\`.\`sales_channel_domain\`…
-
-Starting with **Shopware 6.7.7.0** and **Language Pack 5.37.1**, the migration process was improved. If you encounter this issue,
-please update Shopware to >= 6.7.7.0, Language Pack to >= 5.37.1, remove the translation files created from running the
-command and run the command again. Or follow the updated migration guide.
-
 [translation-system]: ../../../../../concepts/translations/built-in-translation-system.md
 [language-pack-plugin]: https://store.shopware.com/en/swag338126230916f/shopware-language-pack.html
 [shopware-translations]: https://translate.shopware.com
diff --git a/guides/upgrades-migrations/upgrade-shopware b/guides/upgrades-migrations/upgrade-shopware
@@ -0,0 +1,70 @@
+---
+nav:
+  title: Update Shopware
+  position: 10
+---
+
+# Update Shopware
+
+This guide explains how to update an existing Shopware installation using Composer.
+
+For maintaining custom plugins or apps, review the [Upgrades and Migrations](../upgrades-and-migrations/index.md) guide before performing updates.
+
+## Standard update process
+
+Shopware updates must be executed via Composer.
+
+### 1. Enable maintenance mode
+
+Prepare the system for update:
+
+```bash
+bin/console system:update:prepare
+```
+
+This enables maintenance mode and prepares the update process.
+
+### 2. Update Composer dependencies
+
+Update all Composer packages without executing scripts:
+
+```bash
+composer update --no-scripts
+```
+
+The `--no-scripts` flag instructs Composer to avoid running any scripts that may reference Shopware CLI commands. These commands will only work after updated recipes are installed.
+
+### 3. Update Symfony recipes (optional but recommended)
+
+To force-update all configuration files managed by Symfony Flex:
+
+```bash
+composer recipes:update
+```
+
+Review changes carefully before committing them.
+
+### 4. Finalize the update
+
+Disable maintenance mode and complete the update:
+
+```bash
+bin/console system:update:finish
+```
+
+## Operational best practices
+
+* Automate pre-upgrade checks (PHP/DB versions, extensions, disk space).
+* Always test upgrades on staging with production-like data.
+* Keep verified database backups and a recovery plan.
+* Review changelogs and UPGRADE files before applying changes.
+* Track deprecations early and use official tooling (Rector, Administration codemods referenced in [Performing updates](../hosting/installation-updates/performing-updates.md)) to reduce manual work.
+* Avoid skipping major versions.
+* Commit the `composer.lock` file.
+* Run post-upgrade smoke tests.
+
+## After the update
+
+* Clear caches if necessary
+* Rebuild Administration and Storefront assets if required
+* Test critical business flows (checkout, login, API integrations)
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,7 +5,7 @@ nav: @@
     ---
-    # Vue 3 upgrade
+    # Vue 3 Upgrade
     ## Introduction
@@ Expand Down @@