Usos comuns da API do Upcart

Como funciona o padrão da API

A maioria dos scripts da API do Upcart segue o mesmo padrão simples: Escutar um evento do carrinho → Verificar uma condição → Executar uma ação Por exemplo: “Quando o carrinho carregar → verificar se está vazio → ocultar o botão fixo.” 💡 Novo em APIs? Comece com O que é uma API? antes de mergulhar nos exemplos abaixo.

Onde adicionar seus scripts

Todos os scripts abaixo vão em: Cart Editor → Settings → Custom HTML → Scripts (before load) Envolva cada snippet em tags <script>...</script> e salve. Para testar, abra o console das Ferramentas do Desenvolvedor do seu navegador (F12) e procure por mensagens de console.log.

Uma nota sobre callbacks legados vs. modernos

O Upcart tem duas maneiras de escutar eventos do carrinho:

Estilo	Exemplo	Status
Moderno (recomendado)	`upcartSubscribeAddedToCart(fn)`	Atual
Legado (obsoleto)	`upcartOnAddToCart = fn`	Ainda funciona, registra aviso no console

Todos os exemplos abaixo usam a API moderna. Scripts existentes que usam o estilo antigo continuarão funcionando.

Exemplo 1: ocultar o botão de carrinho fixo quando o carrinho está vazio

<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>

Como funciona: upcartSubscribeCartLoaded dispara toda vez que o carrinho é carregado. O callback recebe um event com um objeto cart contendo um array items. Somamos a quantity de cada item para determinar se o carrinho está vazio. ⚠️ IMPORTANTE: event.cart NÃO tem uma propriedade item_count. Você deve calcular o total iterando por event.cart.items.

Exemplo 2: registrar quando um item é adicionado ao carrinho

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>

Propriedades disponíveis em event.item:

Propriedade	Descrição
`event.item.title`	Título do produto
`event.item.quantityAdded`	Número de unidades adicionadas nesta ação
`event.item.quantity`	Quantidade total deste item agora no carrinho
`event.item.variantId`	ID da variante na Shopify
`event.item.handle`	Handle do produto
`event.item.productId`	ID do produto na Shopify
`event.item.finalPrice`	Preço final após descontos
`event.item.image`	URL da imagem do produto

Exemplo 3: integrar com um app de analytics de terceiros (por exemplo, TripleWhale)

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>

Nota: cada app de terceiros é diferente. Verifique com a equipe de suporte do seu app o formato de evento correto.

Exemplo 4: abrir o carrinho automaticamente depois que um produto é adicionado

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>

Nota: se “Open cart drawer on add to cart” já estiver ativado em Cart Editor → Settings → Cart settings, você não precisa deste script.

Função	Quando dispara	O callback recebe
`upcartSubscribeCartLoaded(fn)`	Os dados do carrinho carregam	`{ cart }` - cart tem `.items[]`, `.total`, `.currency`
`upcartSubscribeAddedToCart(fn)`	Item adicionado ao carrinho	`{ item }` - item tem `.title`, `.variantId`, `.quantityAdded`, `.quantity`
`upcartSubscribeCartOpened(fn)`	O cart drawer abre	`{}` (objeto vazio)
`upcartSubscribeCartClosed(fn)`	O cart drawer fecha	`{}` (objeto vazio)
`upcartSubscribeCartUpdated(fn)`	O conteúdo do carrinho muda	`{ cart }`
`upcartSubscribeItemRemoved(fn)`	Item removido	`{ item }`
`upcartSubscribeCheckoutClicked(fn)`	Botão de checkout clicado	`{ event }` - MouseEvent do navegador
`upcartSubscribeUpsellsAddedToCart(fn)`	Item de upsell adicionado	`{ variant }` - tem `.id` e `.title`
`upcartSubscribeUpsellsRendered(fn)`	Os upsells são renderizados no carrinho	`{ item, element }` - item é o produto, element é o nó do DOM
`upcartSubscribeNotesTextChanged(fn)`	As notas do carrinho são atualizadas	`{ newNotesText, oldNotesText }` - a nova string de notas e a anterior
`upcartSubscribeRewardsMilestonesCompletedChanged(fn)`	O status de um marco de recompensa muda	`{ numOfMilestonesCompleted, status }` - `status` é `"promotion"`, `"demotion"` ou `"initial-state"`

Funções de ação direta

Função	O que ela faz
`window.upcartOpenCart()`	Abre o cart drawer
`window.upcartCloseCart()`	Fecha o cart drawer
`window.upcartRefreshCart()`	Atualiza os dados do carrinho
`window.upcartGetCart()`	Retorna o objeto atual do carrinho
`window.upcartRegisterAddToCart()`	Registra o add-to-cart para construtores de páginas (Replo, PageFly etc.)
`window.upcartFormatMoney()`	Formata um preço usando o formato de moeda da sua loja

Para a documentação completa da API, veja a documentação da API pública do Upcart.

Solução de problemas

O script não está rodando? Verifique novamente o posicionamento: ele deve estar em Scripts (before load), não em after load.
Elemento não encontrado? Certifique-se de que o seletor (por exemplo, #upCartStickyButton) corresponde ao ID real do elemento no seu carrinho.
Algo quebrou? Comente seu script adicionando // no início de cada linha, salve e recarregue.
Ainda travado? Veja o FAQ da API para mais etapas de solução de problemas.

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

Como funciona o padrão da API

Onde adicionar seus scripts

Uma nota sobre callbacks legados vs. modernos

Exemplo 1: ocultar o botão de carrinho fixo quando o carrinho está vazio

Exemplo 2: registrar quando um item é adicionado ao carrinho

Exemplo 3: integrar com um app de analytics de terceiros (por exemplo, TripleWhale)

Exemplo 4: abrir o carrinho automaticamente depois que um produto é adicionado

Funções de ação direta

Solução de problemas

​Como funciona o padrão da API

​Onde adicionar seus scripts

​Uma nota sobre callbacks legados vs. modernos

​Exemplo 1: ocultar o botão de carrinho fixo quando o carrinho está vazio

​Exemplo 2: registrar quando um item é adicionado ao carrinho

​Exemplo 3: integrar com um app de analytics de terceiros (por exemplo, TripleWhale)

​Exemplo 4: abrir o carrinho automaticamente depois que um produto é adicionado

​Referência rápida: funções de subscribe (API moderna)

​Funções de ação direta

​Solução de problemas

Como funciona o padrão da API

Onde adicionar seus scripts

Uma nota sobre callbacks legados vs. modernos

Exemplo 1: ocultar o botão de carrinho fixo quando o carrinho está vazio

Exemplo 2: registrar quando um item é adicionado ao carrinho

Exemplo 3: integrar com um app de analytics de terceiros (por exemplo, TripleWhale)

Exemplo 4: abrir o carrinho automaticamente depois que um produto é adicionado

Referência rápida: funções de subscribe (API moderna)

Funções de ação direta

Solução de problemas