Guía de migración a Upcart V2.0

Descripción general

Los módulos de Upcart V2.0 introducen un rediseño arquitectónico completo del sistema del carrito. La actualización se centra en un rendimiento mejorado, una personalización más avanzada y un mejor mantenimiento. Esta guía te ayudará a entender qué cambia al migrar de los módulos V1.0 a V2.0, qué problemas de compatibilidad puedes encontrar y cómo actualizar tus personalizaciones existentes de forma segura.

Cambios importantes: cambios en los nombres de clases CSS

Clases V1 (obsoletas)

🚨 Los siguientes nombres de clase de V1.0 ya no tienen soporte en V2.0:

.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...

Las clases de advertencia de falta de existencias upcart-quantity-warning y upcart-quantity-warning-text tampoco han cambiado. Provienen del inicializador del carrito y no de un módulo con versiones, por lo que se emiten de forma idéntica tanto si tus módulos están en V1 como en V2.

.styles_CartPreview__card__ no está en esta lista: es el envoltorio compartido de la estructura del carrito que se muestra alrededor de cada módulo independientemente de la versión, por lo que las reglas que lo apuntan siguen funcionando en V2. Las clases de recompensas son .styles_Rewards__ (barra simple) y .styles_TieredRewards__ (barra por niveles); no existe .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'

Clases V2.0 (nuevo sistema)

V2.0 introduce un sistema de nomenclatura estructurado con prefijos de clase internos y públicos.

Nombres de clase internos

Están reservados para uso interno y pueden cambiar sin previo aviso. Si sobrescribes estas clases, la compatibilidad futura no está garantizada.

/* Internal classes - for Upcart's internal styling */   
.upcart-internal-header  
.upcart-internal-header__close-button  
.upcart-internal-cart-items  
.upcart-internal-rewards  
...

Nombres de clase públicos

🚨 Lista de nombres de clase públicos disponibles

/*******************  
***** 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'

Estos forman parte de la API pública de estilos (upcart-public-) y es seguro sobrescribirlos para diseños personalizados.

.upcart-public-header  
.upcart-public-header__close-button  
.upcart-public-rewards  
...

✅ Qué HACER

Usa únicamente nombres de clase upcart-public- para los estilos.

/* ✅ Correct usage */  
.upcart-public-header {     
  font-size: 18px;  
  font-weight: bold;   
}

❌ Qué NO hacer

Evita sobrescribir nombres de clase internos

/* ❌ Avoid this */  
.upcart-internal-header {     
  font-size: 18px;  
  font-weight: bold;   
}

Evita apuntar a nodos específicos con selectores profundos o personalizados.

/* ❌ Avoid this */  
.upcart-public-upsell div a {     
  font-size: 18px;  
  font-weight: bold;   
}

Sistema de atributos de datos

V2.0 introduce un sistema estructurado de atributos de datos para mejorar la selección de elementos y la personalización avanzada.

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

Estos atributos facilitan la creación de plantillas flexibles basadas en datos, manteniendo la claridad del código.

Cambios en las variables de plantilla

Los módulos V2 usan una nueva sintaxis de variables de plantilla con llaves dobles {{ }}.

Módulo de anuncios

V1.0: `{TIMER}`
V2.0: `{{timer}}`

Módulo de recompensas por niveles

V1.0: `{AMOUNT}` → V2: `{{amount}}`
V1.0: `{COUNT}` → V2: `{{count}}`

Proceso de migración

1. Haz una copia de seguridad de la configuración actual

Antes de hacer cualquier cambio, haz una copia de seguridad de tus archivos existentes de CSS personalizado y HTML.

2. Prueba en modo sandbox

Configura tu carrito actualizado usando el modo sandbox para probar los nuevos módulos de forma segura antes de publicarlos.

Personalización avanzada con V2.0

Plantillas personalizadas

Los módulos V2.0 admiten plantillas totalmente personalizadas para los comerciantes que quieren control completo sobre el diseño y la estructura. Para habilitar las plantillas personalizadas:

Ve a Settings > Cart settings, expande Advanced Settings y marca Access custom templates. La casilla está dentro de esa sección plegada, no en la propia pestaña Cart settings.
Habilita el interruptor de la función.
Consulta la documentación para desarrolladores de Upcart para ver la sintaxis y ejemplos.

Nota: el equipo de soporte de Upcart no puede ayudar con el desarrollo, la depuración ni la solución de problemas de plantillas personalizadas.

Mejores prácticas

Prueba siempre las actualizaciones primero en modo sandbox.
Migra y actualiza las personalizaciones de forma incremental.
Usa clases públicas para los estilos en lugar de las internas.
Conserva copias de seguridad de todas las versiones anteriores antes de actualizar la configuración en vivo.

Consideraciones futuras

Los módulos V2 seguirán recibiendo nuevas funciones, optimizaciones y actualizaciones.
Los módulos V1 están ahora en modo de mantenimiento, con soporte limitado y sin nuevas funciones.
Se recomienda a los comerciantes migrar a V2 lo antes posible para una compatibilidad total.

Getting Started

Cart Modules

Cart Settings

Sticky Cart Button

Multicart

Customizations

Analytics

Integrations & Compatibility

Billing & Account

Troubleshooting

Descripción general

Cambios importantes: cambios en los nombres de clases CSS

Clases V1 (obsoletas)

Clases V2.0 (nuevo sistema)

Nombres de clase internos

Nombres de clase públicos

✅ Qué HACER

❌ Qué NO hacer

Sistema de atributos de datos

Cambios en las variables de plantilla

Módulo de anuncios

Módulo de recompensas por niveles

Proceso de migración

1. Haz una copia de seguridad de la configuración actual

2. Prueba en modo sandbox

Personalización avanzada con V2.0

Plantillas personalizadas

Mejores prácticas

Consideraciones futuras

​Descripción general

​Cambios importantes: cambios en los nombres de clases CSS

​Clases V1 (obsoletas)

​Clases V2.0 (nuevo sistema)

​Nombres de clase internos

​Nombres de clase públicos

​

​✅ Qué HACER

​❌ Qué NO hacer

​Sistema de atributos de datos

​Cambios en las variables de plantilla

​Módulo de anuncios

​Módulo de recompensas por niveles

​Proceso de migración

​1. Haz una copia de seguridad de la configuración actual

​2. Prueba en modo sandbox

​Personalización avanzada con V2.0

​Plantillas personalizadas

​Mejores prácticas

​Consideraciones futuras

​

​

Descripción general

Cambios importantes: cambios en los nombres de clases CSS

Clases V1 (obsoletas)

Clases V2.0 (nuevo sistema)

Nombres de clase internos

Nombres de clase públicos

✅ Qué HACER

❌ Qué NO hacer

Sistema de atributos de datos

Cambios en las variables de plantilla

Módulo de anuncios

Módulo de recompensas por niveles

Proceso de migración

1. Haz una copia de seguridad de la configuración actual

2. Prueba en modo sandbox

Personalización avanzada con V2.0

Plantillas personalizadas

Mejores prácticas

Consideraciones futuras