Objeto de carrinho

Um único formato de objeto flui por todo o SDK. É o que getCart() retorna, o que cart_loaded e cart_updated entregam ao seu handler e o que um bloco Custom code recebe.

Todo valor monetário está na unidade menor da moeda (centavos para USD), nunca uma string formatada. 5779 é $57.79. Use formatMoney para exibi-lo.

O carrinho

Campo	Tipo	Descrição
`token`	`string`	O token de carrinho do Shopify.
`items`	`AftersellCartLine[]`	Os itens de linha. Veja linhas do carrinho.
`itemCount`	`number`	Quantidade total de itens, como o comprador vê.
`hasSubscriptionItems`	`boolean`	`true` quando pelo menos uma linha em `items` tem um selling plan, incluindo linhas de complemento que o `itemCount` deixa de fora. `false` em um carrinho vazio.
`totalPrice`	`number`	Total atual, em centavos.
`originalTotalPrice`	`number`	Total antes dos descontos, em centavos.
`totalDiscount`	`number`	Total de descontos, em centavos.
`compareAtTotalPrice`	`number \| null`	Soma do preço comparativo (MSRP) de cada linha × quantidade, em centavos. `null` quando indisponível; nesse caso, recorra a `originalTotalPrice`.
`currency`	`string`	Código da moeda.
`discountCodes`	`string[]`	Códigos de desconto aceitos no carrinho, ordenados. `[]` quando não há.
`attributes`	`Record<string, string>`	Atributos do carrinho. Somente leitura pelo SDK.

itemCount nem sempre é a soma de items. items espelha o carrinho real do Shopify, incluindo linhas de complemento que o drawer oculta, como shipping protection. itemCount é o número voltado ao comprador que corresponde ao badge do carrinho. Para “quantas coisas o comprador escolheu”, use itemCount; para iterar sobre as linhas que o carrinho está renderizando, use items.Duas coisas ficam totalmente fora de items: linhas ocultadas com setHidden, e os filhos de bundle, que se movem para a âncora. Ambos ainda contam para os totais do carrinho, que vêm diretamente do Shopify.

window.aftersell.cart.events.on('cart_updated', (state) => {
  console.log(state.itemCount, 'items');
  console.log('Total:', window.aftersell.cart.actions.formatMoney(state.totalPrice));
  console.log('Saved:', window.aftersell.cart.actions.formatMoney(state.totalDiscount));
  console.log('Codes:', state.discountCodes.join(', ') || 'none');
});

Linhas do carrinho

Cada entrada em items, e o item em item_added e item_removed:

Campo	Tipo	Descrição
`key`	`string`	O key da linha no Shopify. Passe-o às ações de item.
`productId`	`number`	ID do produto no Shopify.
`variantId`	`number`	ID da variante no Shopify.
`handle`	`string`	Handle do produto.
`title`	`string`	Título de exibição.
`productTitle`	`string`	Título do produto sem a variante.
`variantTitle`	`string \| null`	Rótulo da variante, ou `null`.
`variantOptions`	`Array<{ name, value }>`	Opções selecionadas, por exemplo `[{ name: 'Size', value: 'Medium' }]`. O Shopify emite `Title: Default Title` para um produto de variante única.
`quantity`	`number`	Quantidade desta linha.
`linePrice`	`number`	Preço da linha, em centavos.
`finalLinePrice`	`number`	Preço da linha após descontos, em centavos.
`originalLinePrice`	`number`	Preço da linha antes dos descontos, em centavos.
`compareAtPrice`	`number \| null`	Preço comparativo (MSRP) da variante por unidade, em centavos. `null` quando não há.
`properties`	`Record<string, string> \| null`	Propriedades do item de linha.
`internalProperties`	`Record<string, string>`	Sobreposição apenas de renderização de `registerLineTransform`. Nunca persistida no Shopify. `{}` quando não há.
`discountAllocations`	`Array<{ title, amount }>`	Descontos aplicados a esta linha. `amount` está em centavos. `[]` quando não há.
`isGiftCard`	`boolean`	Se a linha é um cartão-presente.
`sellingPlan`	`{ id, name } \| null`	O plano de assinatura ativo, ou `null` para uma compra única.
`bundle`	`AftersellCartBundle \| null`	View model de bundle na linha âncora; `null` em linhas que não são bundle e nos filhos.
`metadata`	`Record<string, unknown>`	Dados de enriquecimento indexados pelo `id` do enricher. `{}` até que um enricher os preencha.

properties pode conter entrada fornecida pelo comprador, como o campo de texto personalizado de um formulário de produto. Renderize-o como texto, nunca como HTML bruto.

Identificando uma linha

Use key para qualquer coisa que atue sobre uma linha, e variantId ou productId para qualquer coisa que identifique um produto:

// ✅ Acting on a line: use key.
window.aftersell.cart.actions.removeItem(line.key);

// ✅ Recognising a product: use variantId.
const hasGift = state.items.some((line) => line.variantId === GIFT_VARIANT_ID);

A mesma variante pode aparecer em várias linhas quando as propriedades diferem. Duas canecas gravadas com textos de gravação diferentes são duas linhas compartilhando um mesmo variantId. É por isso que as ações recebem key.

Preços em uma linha

Três preços fáceis de confundir:

Você quer	Use
O que o comprador paga por esta linha	`finalLinePrice`
Quanto custava antes dos descontos do carrinho	`originalLinePrice`
O MSRP riscado, por unidade	`compareAtPrice` × `quantity`

// Is this line discounted?
const isDiscounted = line.finalLinePrice < line.originalLinePrice;

// Is it free? (A common way to detect a gift line.)
const isFree = line.finalLinePrice === 0;

Bundles

Quando linhas são agrupadas em um bundle, a linha âncora carrega um objeto bundle. Os filhos são incorporados a ela e não aparecem mais em items por conta própria. Veja Agrupar linhas de bundle de outro app para saber como o agrupamento é configurado.

Campo	Tipo	Descrição
`id`	`string`	Identificador do bundle.
`source`	`'native' \| 'grouped'`	Um bundle nativo do Shopify, ou linhas agrupadas pelo Aftersell.
`memberKeys`	`string[]`	O `key` de cada linha do bundle.
`children`	`AftersellBundleChild[]`	O conteúdo do bundle.
`displayPrice`	`number`	O preço exibido para o bundle, em centavos.

Cada filho carrega key (null para um componente nativo), title, variantTitle, quantity, perAnchorQty, imageUrl, finalLinePrice, originalLinePrice e compareAtPrice.

// Skip bundle children when totalling your own line list.
const topLevel = state.items.filter((line) => !isBundleChild(line, state));

Planos de assinatura

O plano ativo de uma linha é sellingPlan, ou null para uma compra única. Para uma resposta sobre o carrinho inteiro, leia hasSubscriptionItems em vez de varrer as linhas você mesmo, já que ele também conta linhas de complemento que items apresenta mas itemCount ignora:

if (state.hasSubscriptionItems) {
  // The cart contains at least one subscription line.
}

const subscriptions = state.items.filter((line) => line.sellingPlan);
console.log(subscriptions.length, 'subscription lines');

Os planos disponíveis em uma linha, os que aparecem no seletor, não estão no objeto de carrinho. Modele-os com registerSubscriptionOptionsTransform e registerDefaultSubscriptionOptionSelector.

Para onde ir agora

Ações: leia e altere o carrinho.
Eventos: de onde este objeto vem.
Hooks: adicione seus próprios dados a uma linha com um enricher.
Casos de uso: soluções completas que leem esses campos.

Primeiros passos

Página inicial

Melhores práticas

Upsells pós-compra

Carrinho

Upsells no checkout (Shopify Plus)

Página de agradecimento

Upsells na página de produto

Rokt Thanks

Estratégias

Análises e rastreamento

Integrações

Aftersell MCP

Faturamento e conta

Solução de problemas

O carrinho

Linhas do carrinho

Identificando uma linha

Preços em uma linha

Bundles

Planos de assinatura

Para onde ir agora

​O carrinho

​Linhas do carrinho

​Identificando uma linha

​Preços em uma linha

​Bundles

​Planos de assinatura

​Para onde ir agora

O carrinho

Linhas do carrinho

Identificando uma linha

Preços em uma linha

Bundles

Planos de assinatura

Para onde ir agora