Guia de migração para o Upcart V2.0

Visão geral

Os módulos do Upcart V2.0 introduzem um redesign arquitetural completo do sistema de carrinho. A atualização foca em desempenho aprimorado, personalização avançada e melhor manutenibilidade. Este guia ajudará você a entender o que muda ao migrar dos módulos V1.0 para os V2.0, quais problemas de compatibilidade você pode encontrar e como atualizar suas personalizações existentes com segurança.

Mudanças que quebram compatibilidade - alterações nos nomes de classes CSS

Classes V1 (descontinuadas)

🚨 Os seguintes nomes de classe V1.0 não são mais suportados na V2.0:

.styles_Header__  
.styles_ProductRow__  
.styles_Rewards__  
.styles_TieredRewards__  
...

As classes de aviso de falta de estoque upcart-quantity-warning e upcart-quantity-warning-text também permanecem inalteradas. Elas vêm do inicializador do carrinho e não de um módulo versionado, portanto são emitidas de forma idêntica, estejam seus módulos na V1 ou na V2.

.styles_CartPreview__card__ não está nesta lista — ela é o wrapper compartilhado da estrutura do carrinho renderizado ao redor de cada módulo, independentemente da versão, então regras direcionadas a ela continuam funcionando na V2. As classes de recompensas são .styles_Rewards__ (barra simples) e .styles_TieredRewards__ (barra por níveis); não 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'

Classes V2.0 (novo sistema)

A V2.0 introduz um sistema de nomenclatura estruturado com prefixos de classes internal e public.

Nomes de classe internos

Estes são reservados para uso interno e podem mudar sem aviso prévio. Se você sobrescrever essas classes, a compatibilidade futura não é garantida.

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

Nomes de classe públicos

🚨 Lista de nomes de classe públicos disponíveis

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

Estas fazem parte da API pública de estilização (upcart-public-) e são seguras de sobrescrever para designs personalizados.

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

✅ O QUE FAZER

Use apenas nomes de classe upcart-public- para estilização.

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

❌ O QUE NÃO FAZER

Evite sobrescrever nomes de classe internos

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

Evite direcionar nós específicos com seletores profundos ou personalizados.

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

Sistema de atributos de dados

A V2.0 introduz um sistema estruturado de atributos de dados para melhor direcionamento e personalização avançada.

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

Esses atributos facilitam a criação de templates flexíveis e orientados por dados, mantendo a clareza do código.

Alterações nas variáveis de template

Os módulos V2 usam uma nova sintaxe de variáveis de template com chaves duplas {{ }}.

Módulo Announcement

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

Módulo Tiered Rewards

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

Processo de migração

1. Faça backup da configuração atual

Antes de fazer qualquer alteração, faça backup dos seus arquivos existentes de CSS personalizado e HTML.

2. Teste no modo sandbox

Configure seu carrinho atualizado usando o modo sandbox para testar com segurança os novos módulos antes de ir ao ar.

Personalização avançada com a V2.0

Templates personalizados

Os módulos V2.0 suportam templates totalmente personalizados para lojistas que querem controle completo sobre o layout e a estrutura. Para ativar os templates personalizados:

Vá para Settings > Cart settings, expanda Advanced Settings e marque Access custom templates. A caixa de seleção está dentro dessa seção recolhida, não na própria aba Cart settings.
Ative o botão do recurso.
Consulte a documentação para desenvolvedores do Upcart para sintaxe e exemplos.

Caixa de seleção Access custom templates ativada com sua descrição nas configurações de carrinho do Upcart

Nota: a equipe de suporte do Upcart não pode ajudar no desenvolvimento, na depuração ou na solução de problemas de templates personalizados.

Boas práticas

Sempre teste as atualizações primeiro no modo sandbox.
Migre e atualize as personalizações de forma incremental.
Use classes públicas para estilização em vez das internas.
Mantenha backups de todas as versões anteriores antes de atualizar as configurações ativas.

Considerações futuras

Os módulos V2 continuarão recebendo novos recursos, otimizações e atualizações.
Os módulos V1 agora estão em modo de manutenção, com suporte limitado e sem novos recursos.
Incentivamos os lojistas a migrar para a V2 o quanto antes para compatibilidade total.

Primeiros passos

Módulos do carrinho

Configurações do carrinho

Botão de carrinho fixo

Multicart

Personalizações

Análises

Integrações e compatibilidade

Faturamento e conta

Solução de problemas

Visão geral

Mudanças que quebram compatibilidade - alterações nos nomes de classes CSS

Classes V1 (descontinuadas)

Classes V2.0 (novo sistema)

Nomes de classe internos

Nomes de classe públicos

✅ O QUE FAZER

❌ O QUE NÃO FAZER

Sistema de atributos de dados

Alterações nas variáveis de template

Módulo Announcement

Módulo Tiered Rewards

Processo de migração

1. Faça backup da configuração atual

2. Teste no modo sandbox

Personalização avançada com a V2.0

Templates personalizados

Boas práticas

Considerações futuras

​Visão geral

​Mudanças que quebram compatibilidade - alterações nos nomes de classes CSS

​Classes V1 (descontinuadas)

​Classes V2.0 (novo sistema)

​Nomes de classe internos

​Nomes de classe públicos

​

​✅ O QUE FAZER

​❌ O QUE NÃO FAZER

​Sistema de atributos de dados

​Alterações nas variáveis de template

​Módulo Announcement

​Módulo Tiered Rewards

​Processo de migração

​1. Faça backup da configuração atual

​2. Teste no modo sandbox

​Personalização avançada com a V2.0

​Templates personalizados

​Boas práticas

​Considerações futuras

​

​

Visão geral

Mudanças que quebram compatibilidade - alterações nos nomes de classes CSS

Classes V1 (descontinuadas)

Classes V2.0 (novo sistema)

Nomes de classe internos

Nomes de classe públicos

✅ O QUE FAZER

❌ O QUE NÃO FAZER

Sistema de atributos de dados

Alterações nas variáveis de template

Módulo Announcement

Módulo Tiered Rewards

Processo de migração

1. Faça backup da configuração atual

2. Teste no modo sandbox

Personalização avançada com a V2.0

Templates personalizados

Boas práticas

Considerações futuras