> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Upcart V2.0-Migrationsleitfaden
> Dieser Artikel ist ein Migrationsleitfaden für das Upgrade von Upcart V1.0- auf V2.0-Module. Er behandelt Breaking Changes, CSS-Klassen-Zuordnungen, JavaScript-Selektor-Updates, Fehlerbehebung und den schrittweisen Migrationsprozess.
## Überblick
Die Upcart V2.0-Module führen ein vollständiges architektonisches Redesign des Warenkorbsystems ein. Das Update konzentriert sich auf verbesserte Performance, erweiterte Anpassungsmöglichkeiten und bessere Wartbarkeit.
Dieser Leitfaden hilft dir zu verstehen, was sich bei der Migration von V1.0- auf V2.0-Module ändert, welche Kompatibilitätsprobleme auftreten können und wie du deine bestehenden Anpassungen sicher aktualisierst.
***
## Breaking Changes – Änderungen der CSS-Klassennamen
### V1-Klassen (veraltet)
🚨 Die folgenden V1.0-Klassennamen werden in V2.0 nicht mehr unterstützt:
```
.styles_Header__
.styles_ProductRow__
.styles_Rewards__
.styles_TieredRewards__
...
```
Die Klassen für die Nicht-auf-Lager-Warnung `upcart-quantity-warning` und `upcart-quantity-warning-text` sind ebenfalls **unverändert**. Sie stammen vom Cart-Initializer und nicht von einem versionierten Modul, daher werden sie identisch ausgegeben, egal ob deine Module auf V1 oder V2 laufen.
**`.styles_CartPreview__card__` ist nicht in dieser Liste** — es ist der gemeinsame Cart-Shell-Wrapper, der unabhängig von der Version um jedes Modul gerendert wird. Regeln, die darauf abzielen, funktionieren also auch in V2 weiterhin. Die Rewards-Klassen sind `.styles_Rewards__` (einfacher Balken) und `.styles_TieredRewards__` (gestaffelter Balken); es gibt kein `.styles_RewardsModule__`.
```
/*******************
*** Cart Header ***
*******************/
'upcart-header',
'upcart-header-text',
'upcart-header-logo',
'upcart-header-close-button',
'upcart-header-close-button-icon',
/******************
*** Line Items ***
******************/
'upcart-products-section',
'upcart-product-item',
/** > Title */
'upcart-product-title',
'upcart-product-title-link',
/** > Prices */
'upcart-item-prices-row',
'upcart-item-price',
'upcart-item-compare-price',
'upcart-product-savings',
/** > Options/Variants */
'upcart-item-option',
'upcart-item-option-category',
'upcart-item-option-value',
/** > Bundle Item Components */
'upcart-bundle-item-image-wrapper',
'upcart-bundle-item-product-title',
'upcart-bundle-item-variant-title',
'upcart-bundle-detail-toggle',
/** > Properties */
'upcart-item-properties',
'upcart-item-property',
'upcart-item-property-subscription',
/** > Quantity Selector */
'upcart-product-quantity-input',
'upcart-product-quantity-minus',
'upcart-product-quantity-plus',
/** > Image */
'upcart-product-image-wrapper',
/*********************
*** Announcements ***
*********************/
'upcart-announcement',
/***************
*** Rewards ***
***************/
'upcart-rewards',
'upcart-rewards-message',
'upcart-rewards-bar-background',
'upcart-rewards-bar-foreground',
'upcart-rewards-tier',
'upcart-rewards-tier-circle',
'upcart-rewards-tier-icon',
'upcart-rewards-tier-description',
/***************
*** Upsells & Recommendations ***
***************/
'upcart-upsells-module',
'upcart-upsells-title',
'upcart-upsells-button',
'upcart-upsell-item-title',
'upcart-upsell-item-card',
'upcart-upsell-item-image-wrapper',
'upcart-upsell-item-image',
'upcart-upsell-item-price',
'upcart-upsell-item-price-row',
'upcart-upsell-item-compare-price',
'upcart-upsell-item-variant-selector',
'upcart-upsells', // deprecated
'upcart-recommendation-module',
'upcart-recommendations-title',
'upcart-recommendations-shop-now-button',
/***************
*** Add-ons ***
***************/
'upcart-addons',
'upcart-addons-title',
'upcart-addons-product-description',
'upcart-addons-price',
'upcart-addons-compare-price',
'upcart-addons-toggle',
'upcart-addons-image-wrapper',
/**********************
*** Discount Codes ***
**********************/
'upcart-discount-code-row',
'upcart-discount-code-module',
'upcart-discount-code-button',
'upcart-discount-code-input',
'upcart-discount-code-badge',
'upcart-discount-code-icon',
'upcart-discount-code-text',
'upcart-discount-code-input-wrapper',
/*****************************
*** Subscription Upgrades ***
*****************************/
'upcart-subscription-upgrade-section',
'upcart-subscription-upgrade-button',
'upcart-subscription-upgrade-dropdown',
/***************************
*** Express Pay Buttons ***
***************************/
'upcart-express-pay-buttons-container',
'upcart-express-pay-buttons-row',
'upcart-express-pay-button',
'upcart-express-pay-button-shop-pay',
'upcart-express-pay-button-google-pay',
'upcart-express-pay-button-paypal',
'upcart-express-pay-button-apple-pay',
'upcart-express-pay-button-amazon-pay',
'upcart-express-pay-button-meta-pay',
/********************
*** Trust Badges ***
********************/
'upcart-trust-badge',
'upcart-trust-badge-image',
/********************
*** Integrations ***
********************/
'upcart-integration-zapiet-pickup',
/*****************
*** Skeletons ***
*****************/
'upcart-skeleton',
'upcart-product-item-skeleton',
'upcart-product-image-skeleton',
'upcart-product-title-skeleton',
'upcart-item-option-skeleton',
'upcart-product-quantity-skeleton',
'upcart-product-price-container-skeleton',
'upcart-announcement-skeleton',
'upcart-rewards-skeleton',
'upcart-rewards-message-skeleton',
'upcart-rewards-bar-skeleton',
'upcart-upsells-module-skeleton',
'upcart-upsells-title-skeleton',
'upcart-upsell-item-image-skeleton',
'upcart-upsell-item-title-skeleton',
'upcart-upsell-item-price-skeleton',
'upcart-upsells-button-skeleton',
'upcart-trust-badge-skeleton',
'upcart-trust-badge-image-skeleton',
'upcart-checkout-button-container-skeleton',
'upcart-checkout-button-skeleton',
'upcart-addons-skeleton',
'upcart-addons-image-wrapper-skeleton',
'upcart-addons-skeleton-text-container',
'upcart-discount-code-module-skeleton',
'upcart-discount-code-input-skeleton',
'upcart-discount-code-button-skeleton',
'upcart-express-pay-buttons-container-skeleton',
'upcart-express-pay-button-skeleton'
```
### V2.0-Klassen (neues System)
V2.0 führt ein strukturiertes Benennungssystem mit **internen** und **öffentlichen** Klassen-Präfixen ein.
#### Interne Klassennamen
Diese sind für den internen Gebrauch reserviert und können sich ohne Vorankündigung ändern.
Wenn du diese Klassen überschreibst, ist zukünftige Kompatibilität nicht garantiert.
```
/* Internal classes - for Upcart's internal styling */
.upcart-internal-header
.upcart-internal-header__close-button
.upcart-internal-cart-items
.upcart-internal-rewards
...
```
#### Öffentliche Klassennamen
🚨 Liste der verfügbaren öffentlichen Klassennamen
```
/*******************
***** Skeleton *****
*******************/
'upcart-public-skeleton'
/*******************
****** Header ******
*******************/
'upcart-public-header'
'upcart-public-header__close-button'
'upcart-public-header__close-button-icon'
/*******************
*** Announcement ***
*******************/
'upcart-public-announcement'
/*******************
** Recommendation **
****** Upsell ******
*******************/
'upcart-public-component-upsell-tile'
'upcart-public-component-upsell-tile__image-container'
'upcart-public-component-upsell-tile__image'
'upcart-public-component-upsell-tile__info'
'upcart-public-component-upsell-tile__title-link'
'upcart-public-component-upsell-tile__title'
'upcart-public-component-upsell-tile__rating-row'
'upcart-public-component-upsell-tile__stars'
'upcart-public-component-upsell-tile__star--partial'
'upcart-public-component-upsell-tile__reviews'
'upcart-public-component-upsell-tile__price-row'
'upcart-public-component-upsell-tile__price-compare-at'
'upcart-public-component-upsell-tile__price'
'upcart-public-component-upsell-tile__variant-row'
'upcart-public-component__button'
'upcart-public-component-loader'
'upcart-public-upsell__skeleton'
'upcart-public-upsell__skeleton-title'
'upcart-public-upsell__skeleton-image'
'upcart-public-upsell__skeleton-product-title'
'upcart-public-upsell__skeleton-product-price'
/*******************
****** Notes *******
*******************/
'upcart-public-notes'
'upcart-public-component-collapse__dropdown-container'
'upcart-public-component-collapse__expand-icon'
'upcart-public-notes__text-container'
'upcart-public-notes__textarea'
/*******************
** Discount Code ***
*******************/
'upcart-public-discount-code'
'upcart-public-discount-code__form'
'upcart-public-discount-code__input-wrapper'
'upcart-public-discount-code__input'
'upcart-public-discount-code__suffix'
'upcart-public-discount-code__error'
'upcart-public-discount-code__button'
'upcart-public-component__button'
'upcart-public-skeleton'
'upcart-public-discount-code__skeleton'
'upcart-public-discount-code__skeleton-input'
'upcart-public-discount-code__skeleton-button'
/*******************
** Trust Badges ****
*******************/
'upcart-public-trust-badges'
'upcart-public-trust-badges__image'
/*******************
** Tiered Rewards **
*******************/
'upcart-public-rewards'
'upcart-public-rewards__message'
'upcart-public-rewards__bar'
'upcart-public-component-segmented-progress-bar'
'upcart-public-component-segmented-progress-bar__segments-container'
'upcart-public-component-segmented-progress-bar__segment'
'upcart-public-component-segmented-progress-bar__segment-fill'
'upcart-public-component-segmented-progress-bar__milestone'
'upcart-public-component-segmented-progress-bar__milestone--bottom'
'upcart-public-component-segmented-progress-bar__milestone--top'
'upcart-public-component-segmented-progress-bar__milestone--middle'
'upcart-public-component-segmented-progress-bar__milestone-icon'
'upcart-public-component-segmented-progress-bar__milestone-label'
'upcart-public-component-segmented-progress-bar__milestone-label--align-right'
'upcart-public-component-segmented-progress-bar__milestone-label--align-center'
'upcart-public-rewards__skeleton',
'upcart-public-rewards__skeleton-message',
'upcart-public-rewards__skeleton-bar',
/*******************
**** Cart Items ****
*******************/
'upcart-public-component-product-tile'
'upcart-public-component-product-tile__content'
'upcart-public-component-product-tile__image-wrapper'
'upcart-public-component-product-tile__image'
'upcart-public-component-product-tile__info'
'upcart-public-component-product-tile__header'
'upcart-public-component-product-tile__product-title'
'upcart-public-component-product-tile__title-link'
'upcart-public-component-product-tile__remove-button'
'upcart-public-component-loader'
'upcart-public-component-product-tile__variant'
'upcart-public-component-product-tile__properties'
'upcart-public-component-product-tile__bundle'
'upcart-public-component-product-tile__product-pricing'
'upcart-public-component-product-tile__price-compare-at'
'upcart-public-component-product-tile__price'
'upcart-public-component-product-tile__savings'
'upcart-public-component-product-tile__controls'
'upcart-public-component-product-tile__quantity-selector'
'upcart-public-component-product-tile__quantity-minus'
'upcart-public-component-product-tile__quantity-plus'
'upcart-public-component-product-tile__discount-codes'
'upcart-public-component-tag'
'upcart-public-component-tag__icon'
'upcart-public-component-tag__text'
'upcart-public-component-product-tile__subscription-upgrade'
'upcart-public-component__button'
'upcart-public-component-product-tile__select-wrapper'
'upcart-public-component-product-tile__select'
'upcart-public-product-properties__subscription'
'upcart-public-product-properties__item'
'upcart-public-product-properties__link'
'upcart-public-cart-items__key-value-pair'
'upcart-public-bundle-properties'
'upcart-public-bundle-properties__variant-title'
'upcart-public-component-collapse__dropdown-container'
'upcart-public-bundle-properties__header'
'upcart-public-component-collapse__expand-icon'
'upcart-public-notes__text-container'
'upcart-public-bundle-properties__item-components'
'upcart-public-bundle-properties__item-component-row'
'upcart-public-bundle-properties__image-wrapper'
'upcart-public-bundle-properties__content'
'upcart-public-bundle-properties__product-title'
'upcart-public-upsell__skeleton'
'upcart-public-upsell__skeleton-title'
'upcart-public-upsell__skeleton-image'
'upcart-public-upsell__skeleton-product-title'
'upcart-public-upsell__skeleton-product-price'
/*******************
***** Add-ons ******
*******************/
'upcart-public-addons'
'upcart-public-addons__image-wrapper'
'upcart-public-addons__content-wrapper'
'upcart-public-addons__content-title-wrapper'
'upcart-public-addons__content-title'
'upcart-public-addons__content-price'
'upcart-public-addons__compare-at-price'
'upcart-public-addons__price'
'upcart-public-addons__content-description'
'upcart-public-addons__toggle-wrapper'
'upcart-public-addons__toggle'
'upcart-public-addons__toggle-switch'
'upcart-public-addons__toggle-slider'
'upcart-public-skeleton'
'upcart-public-addons__skeleton'
'upcart-public-addons__skeleton-image'
'upcart-public-addons__skeleton-text'
/*******************
*** Cart summary ***
*******************/
'upcart-public-cart-summary'
'upcart-public-cart-summary__discount-codes'
'upcart-public-cart-summary__discount-label'
'upcart-public-cart-summary__slide-codes'
'upcart-public-cart-summary__total-discount'
```
Diese sind Teil der öffentlichen Styling-API (`upcart-public-`) und können für benutzerdefinierte Designs sicher überschrieben werden.
```
.upcart-public-header
.upcart-public-header__close-button
.upcart-public-rewards
...
```
###
### ✅ DOs
Verwende nur `upcart-public-`-Klassennamen für das Styling.
```
/* ✅ Correct usage */
.upcart-public-header {
font-size: 18px;
font-weight: bold;
}
```
### ❌ DON'Ts
Vermeide es, interne Klassennamen zu überschreiben.
```
/* ❌ Avoid this */
.upcart-internal-header {
font-size: 18px;
font-weight: bold;
}
```
Vermeide es, bestimmte Knoten mit tiefen oder benutzerdefinierten Selektoren anzusprechen.
```
/* ❌ Avoid this */
.upcart-public-upsell div a {
font-size: 18px;
font-weight: bold;
}
```
***
## Datenattribut-System
V2.0 führt ein strukturiertes **Datenattribut-System** für verbessertes Targeting und erweiterte Anpassung ein.
```
```
Diese Attribute erleichtern das Erstellen flexibler, datengesteuerter Templates bei gleichzeitig klarem Code.
***
## Änderungen der Template-Variablen
V2-Module verwenden eine **neue Syntax für Template-Variablen** mit doppelten geschweiften Klammern `{{ }}`.
## Announcement-Modul
* V1.0: `` `{TIMER}` ``
* V2.0: `` `{{timer}}` ``
## Tiered-Rewards-Modul
* V1.0: `` `{AMOUNT}` `` → V2: `` `{{amount}}` ``
* V1.0: `` `{COUNT}` `` → V2: `` `{{count}}` ``
***
## Migrationsprozess
#### 1. Aktuelle Konfiguration sichern
Bevor du Änderungen vornimmst, sichere deine bestehenden **Custom-CSS**- und **HTML**-Dateien.
#### 2. Im Sandbox-Modus testen
Richte deinen aktualisierten Warenkorb im **Sandbox-Modus** ein, um neue Module sicher zu testen, bevor sie live gehen.
***
## Erweiterte Anpassung mit V2.0
### Benutzerdefinierte Templates
V2.0-Module unterstützen vollständig **benutzerdefinierte Templates** für Händler:innen, die die vollständige Kontrolle über Layout und Struktur haben möchten.
So aktivierst du benutzerdefinierte Templates:
1. Gehe zu **Settings > Cart settings**, klappe **Advanced Settings** auf und aktiviere das Kontrollkästchen **Access custom templates**. Das Kontrollkästchen befindet sich innerhalb dieses eingeklappten Abschnitts, nicht direkt auf dem Tab „Cart settings“.
2. Aktiviere den Feature-Schalter.
3. Sieh in der Entwicklerdokumentation von Upcart nach Syntax und Beispielen.
**Hinweis:** Das Support-Team von Upcart kann nicht bei der Entwicklung, dem Debugging oder der Fehlerbehebung benutzerdefinierter Templates helfen.
***
## Best Practices
* Teste Updates immer zuerst im **Sandbox-Modus**.
* Migriere und aktualisiere Anpassungen schrittweise.
* Verwende **öffentliche Klassen** für das Styling statt interner.
* Bewahre Backups aller vorherigen Versionen auf, bevor du Live-Einstellungen aktualisierst.
***
## Ausblick
* V2-Module erhalten weiterhin neue Funktionen, Optimierungen und Updates.
* V1-Module befinden sich jetzt im **Wartungsmodus** mit eingeschränktem Support und ohne neue Funktionen.
* Händler:innen wird empfohlen, so bald wie möglich auf V2 zu migrieren, um volle Kompatibilität zu gewährleisten.
##
##