# Shopware 6.6 → 6.7 Migration: Complete Checklist and Update Pitfalls in 2026

> Field report on Shopware 6.6 → 6.7 migration: Payment API breaking changes, admin overhaul Vue 3 + mt-* components, Vite manifest, OpenSearch 2.19. 8-step checklist and the silent pitfalls we encountered for real on several stores.

- Page: <https://www.datafirefly.com/en/2026/06/06/shopware-6-6-to-6-7-migration-checklist-pitfalls-2026/>
- Language: en
- Published: 2026-06-06
- Last updated: 2026-08-05
- Other languages: [fr](https://www.datafirefly.com/2026/06/06/migration-shopware-6-6-vers-6-7-checklist-pieges-2026/index.md), [es](https://www.datafirefly.com/es/2026/06/06/migracion-shopware-6-6-a-6-7-checklist-trampas-2026/index.md), [de](https://www.datafirefly.com/de/2026/06/06/shopware-6-6-zu-6-7-migration-checkliste-fallstricke-2026/index.md), [it](https://www.datafirefly.com/it/2026/06/06/migrazione-shopware-6-6-verso-6-7-checklist-insidie-2026-2/index.md), [pl](https://www.datafirefly.com/pl/2026/06/06/migracja-shopware-6-6-na-6-7-lista-kontrolna-pulapki-2026/index.md), [nl](https://www.datafirefly.com/nl/2026/06/06/migratie-shopware-6-6-naar-6-7-checklist-valkuilen-2026/index.md), [pt](https://www.datafirefly.com/pt/2026/06/06/migracao-shopware-6-6-para-6-7-checklist-armadilhas-2026/index.md)
- Index: <https://www.datafirefly.com/en/2026/llms.txt>

Shopware 6.7 was released in late 2024 with what the official documentation qualifies as a "major release with multiple breaking changes". For stores on 6.6, migration is mandatory eventually — Shopware only maintains the latest stable version and the previous version in parallel, so staying on 6.5 or 6.6 too long cuts off access to security fixes. For plugins developed in 6.6, several critical APIs have changed signature or been removed between 6.6 and 6.7.

This article is a direct experience report on the 6.6 → 6.7 migration we've conducted on several stores in 2025-2026, with the real technical pitfalls we encountered and the patches we had to produce to adapt our own and third-party plugins. The goal: spare other teams the month of debugging we spent on certain silent regressions.

## What really changes in Shopware 6.7

Beyond the release marketing, here are the 6.7 changes with concrete impact on existing plugins.

**Payment Handler API overhaul.** The `AsynchronousPaymentHandlerInterface` is removed in 6.7. Any payment plugin that implemented this interface in 6.6 must migrate to `AbstractPaymentHandler`. The `pay()` and `finalize()` methods have different signatures: the `AsyncPaymentTransactionStruct` struct is replaced by `PaymentTransactionStruct`, more minimal and DDD-oriented.

**Modified service tags.** The `shopware.payment.method.async` tag that distinguished synchronous and asynchronous payments is removed in favour of a unified `shopware.payment.method` tag. If your services.xml used the old tag, the payment handler no longer registers properly and the payment method disappears from checkout without visible error.

**Admin Vue 2 → Vue 3 migration.** The Shopware 6.7 admin is ported to Vue 3 (whereas 6.6 was on Vue 2 with compat layer). The `sw-*` components (legacy) are being replaced by `mt-*` components (Meteor design system). Many `sw-*` components are marked deprecated and will be removed in a later 6.x release. Admin plugins that used sw-* components must migrate.

**Admin translation system modified.** The `$tc()` methods (translation choice, plural handling) have been replaced by `$t()` with native plural handling. Your admin templates that did `{{ $tc('my.plugin.label') }}` must switch to `{{ $t('my.plugin.label') }}`.

**Admin build via Vite.** The admin now compiles via Vite with a `manifest.json` structured differently from 6.6. Plugins that injected their admin JS via the historical mechanism must adapt their build pipeline to generate the right manifest, otherwise the admin loads empty JS instead of your code.

**Storefront: Bootstrap 5.3 generalised.** The move to Bootstrap 5.3 in the storefront activates native support for `data-bs-theme`, which simplifies dark mode implementations — the subject of our  which exploits this convention. Custom themes based on Bootstrap 5.2 or earlier may have SCSS variables that no longer map.

**PHP and MySQL compatibility.** 6.7 requires PHP 8.2+ (PHP 8.1 EOL, PHP 8.3 recommended) and MySQL 8.0+ or MariaDB 11.4 LTS. Hosting still on MySQL 5.7 or MariaDB 10.x must migrate their DB before the application upgrade.

## The plugin-by-plugin breaking changes we encountered

On the stores we migrated, here are the concrete bugs discovered at upgrade 6.6 → 6.7.

**MoptWorldline (Worldline / SaferPay payment).** The Worldline payment plugin in 6.6 version implemented `AsynchronousPaymentHandlerInterface`. At the 6.7 transition, the plugin no longer loads correctly, and Worldline payment methods disappear from checkout. The patch requires migrating to `AbstractPaymentHandler` and rewriting `pay()` and `finalize()` methods with the new `PaymentTransactionStruct` signature. Estimated work: 2-4 days for an experienced Shopware dev.

**Custom admin plugins with sw-* components.** On our MySmartBook and other plugins, several custom admin components used `sw-card`, `sw-button`, `sw-text-field`, etc. In 6.7, these components still exist but are marked deprecated. The `mt-card`, `mt-button`, `mt-text-field` components replace them. The migration is mechanical but requires exhaustive review of all admin files.

**Snippets and translations.** Snippet files in 6.6 sometimes used the pluralised structure that `$tc()` consumed. In 6.7 with `$t()`, some snippet structures no longer work identically. To test systematically, especially on snippets with counters ("1 product" / "N products").

**Custom field customer and synchronisation.** Our  stores user preference in a `df_dark_mode_preference` custom field on the customer entity. The 6.7 migration preserved custom fields compatibility, but the synchronisation API has a slightly different signature. To test systematically after upgrade.

**OpenSearch 2.19+ mandatory.** If your store uses fulltext search with OpenSearch (formerly Elasticsearch in earlier Shopware versions), 6.7 requires OpenSearch 2.19 minimum. OpenSearch 1.x versions are no longer supported. OpenSearch cluster migration to plan before the application upgrade.

## The migration checklist in 8 steps

For a controlled 6.6 → 6.7 migration, here's the order we follow internally.

**Step 1 — Audit installed plugins.** List all plugins activated on your store. For each one, check on the store or GitHub if a 6.7-compatible version exists. Plugins not updated are major risks: to deactivate temporarily, patch internally, or replace.

**Step 2 — Audit custom theme.** If you use a custom theme (and not the native Storefront theme), check compatibility with Bootstrap 5.3, base layout structure changes, and the Vite admin system if your theme injects custom admin JS.

**Step 3 — Infrastructure environment update.** PHP 8.2+, MySQL 8 or MariaDB 11.4 LTS, OpenSearch 2.19+ if used, recent Node.js (18+ or 20 LTS). To do before the Shopware application upgrade.

**Step 4 — Complete backup.** Database + files folder + `config/` files. It's the step we tend to neglect until the moment the upgrade irretrievably breaks something. To do systematically before any change.

**Step 5 — Migration on staging environment.** Clone the prod to an identical staging, do the 6.7 upgrade on the staging, validate exhaustively before touching the prod. It's not optional — on the stores we migrated, 30% had critical bugs discovered only in staging.

**Step 6 — Shopware application upgrade.** Via the SUM (Shopware Update Manager) in CLI: `bin/console system:update:prepare`, then `bin/console system:update:finish`. Read the official documentation carefully for options (skip-asset-build, etc.). Count 30 min to 2 h depending on database size.

**Step 7 — Theme and admin recompilation.** After the core upgrade, recompile the theme (`bin/console theme:compile`) and rebuild the admin (`bin/build-administration.sh`). On Shopware 6.7, the admin compiles via Vite; the historical theme:compile command no longer suffices for the admin.

**Step 8 — Exhaustive post-upgrade testing.** Complete journey: catalogue navigation, product page, add to cart, checkout, payment (each payment method tested individually), customer area, admin (each installed module). On B2B stores, also test quotes, hierarchical accounts, per-customer pricing.

## The silent pitfalls we encountered in real life

Beyond documented breaking changes, here are the subtle bugs that don't show immediately after the upgrade.

**The payment handler that no longer registers.** As mentioned above, a payment plugin with old tag `shopware.payment.method.async` no longer registers in 6.7. The payment method disappears from checkout, but no error is raised — the corresponding payment_method_id still exists in the database, the handler is simply no longer instantiated. Client-side symptom: the method is displayed in admin (configuration / sales channels / payment methods) but doesn't appear at checkout.

**The custom admin component that renders empty.** A component that used `$tc()` without any associated translation (case of hardcoded labels) no longer renders anything in 6.7. No error in the console, simply an empty placeholder. To detect by manual review of custom admin screens after upgrade.

**The Vite manifest that doesn't generate.** If your custom admin plugin was built with a personalised script in 6.6 (webpack or direct rollup), this build may not generate the manifest.json expected by Shopware 6.7. Symptom: the admin loads but your plugin JS isn't executed. Solution: adapt the build to export a Vite-compatible manifest.

**Pluralised snippets that no longer translate.** If you had snippets with structure `{count} | one thing | {count} things` consumed by `$tc()`, the switch to `$t()` requires different syntax. Non-migrated snippets display the raw template string instead of the translation.

**The custom field that no longer exists in API.** Some modifications of the DAL (Data Abstraction Layer) API in 6.7 changed the serialisation of certain complex custom fields (multi-select, JSON). The values in database still exist, but are read differently. To test on critical custom fields.

## Conclusion: a necessary migration to anticipate

The Shopware 6.6 → 6.7 migration is not a simple minor update. It introduces significant breaking changes that require real work on plugins (payment notably), custom admin, and infrastructure. Stores that do this migration in 1 day "because we just clicked Update" discover bugs in production weeks later, sometimes with direct revenue impact (broken payment, unusable admin).

The realistic time investment for a store with 5-10 third-party plugins and a custom theme is 5 to 15 man-days for an experienced Shopware developer, plus a few days of acceptance testing. Anticipating the topic, doing the upgrade on staging, testing exhaustively before prod — that's what distinguishes a controlled migration from a crisis migration.

For related technical topics, browse our  and  categories. And if you're looking for Shopware 6.7 plugins that are French, performance-first, and well-maintained, our  is Shopware 6.7-compatible from release and illustrates the technical patterns aligned with the new architecture (anti-FOUC, customer custom field, JS events for third-party synchronisation).

Also worth reading: [the PrestaShop 1.7 to 8 migration checklist](https://www.datafirefly.com/en/2026/06/10/prestashop-1-7-to-8-migration-checklist-2026/) and [PrestaShop 9 vs PrestaShop 8](https://www.datafirefly.com/en/2026/05/01/prestashop-9-vs-prestashop-8-changes-2026/).