Upcart V2.0-Migrationsleitfaden

Ü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.

<!-- V2 data attributes for targeting -->   
<div data-upcart-chunk="header-title-content" />     
<div data-internal-properties="hasNonDefaultTitleAlignment=true" />       
<div data-placement="topOfFooter" />

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:

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“.
Aktiviere den Feature-Schalter.
Sieh in der Entwicklerdokumentation von Upcart nach Syntax und Beispielen.

Aktiviertes Kontrollkästchen „Access custom templates“ mit Beschreibung in den Upcart-Warenkorbeinstellungen

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.

Erste Schritte

Warenkorb-Module

Warenkorb-Einstellungen

Sticky-Warenkorb-Button

Multicart

Anpassungen

Analytics

Integrationen & Kompatibilität

Abrechnung & Konto

Fehlerbehebung

Überblick

Breaking Changes – Änderungen der CSS-Klassennamen

V1-Klassen (veraltet)

V2.0-Klassen (neues System)

Interne Klassennamen

Öffentliche Klassennamen

✅ DOs

❌ DON’Ts

Datenattribut-System

Änderungen der Template-Variablen

Announcement-Modul

Tiered-Rewards-Modul

Migrationsprozess

1. Aktuelle Konfiguration sichern

2. Im Sandbox-Modus testen

Erweiterte Anpassung mit V2.0

Benutzerdefinierte Templates

Best Practices

Ausblick

​Überblick

​Breaking Changes – Änderungen der CSS-Klassennamen

​V1-Klassen (veraltet)

​V2.0-Klassen (neues System)

​Interne Klassennamen

​Öffentliche Klassennamen

​

​✅ DOs

​❌ DON’Ts

​Datenattribut-System

​Änderungen der Template-Variablen

​Announcement-Modul

​Tiered-Rewards-Modul

​Migrationsprozess

​1. Aktuelle Konfiguration sichern

​2. Im Sandbox-Modus testen

​Erweiterte Anpassung mit V2.0

​Benutzerdefinierte Templates

​Best Practices

​Ausblick

​

​

Überblick

Breaking Changes – Änderungen der CSS-Klassennamen

V1-Klassen (veraltet)

V2.0-Klassen (neues System)

Interne Klassennamen

Öffentliche Klassennamen

✅ DOs

❌ DON’Ts

Datenattribut-System

Änderungen der Template-Variablen

Announcement-Modul

Tiered-Rewards-Modul

Migrationsprozess

1. Aktuelle Konfiguration sichern

2. Im Sandbox-Modus testen

Erweiterte Anpassung mit V2.0

Benutzerdefinierte Templates

Best Practices

Ausblick