Oggetto cart

Un’unica struttura di oggetto attraversa l’intero SDK. È ciò che getCart() restituisce, ciò che cart_loaded e cart_updated passano al tuo handler e ciò che riceve un blocco Custom code.

Tutti gli importi sono nell’unità minore della valuta (centesimi per USD), mai una stringa formattata. 5779 è $57.79. Usa formatMoney per visualizzarli.

Il carrello

Campo	Tipo	Descrizione
`token`	`string`	Il token del carrello di Shopify.
`items`	`AftersellCartLine[]`	Le line item. Vedi righe del carrello.
`itemCount`	`number`	Quantità totale di articoli, come la vede l’acquirente.
`hasSubscriptionItems`	`boolean`	`true` quando almeno una riga in `items` ha un selling plan, incluse le righe add-on che `itemCount` esclude. `false` su un carrello vuoto.
`totalPrice`	`number`	Totale corrente, in centesimi.
`originalTotalPrice`	`number`	Totale prima degli sconti, in centesimi.
`totalDiscount`	`number`	Totale degli sconti, in centesimi.
`compareAtTotalPrice`	`number \| null`	Somma del compare-at (MSRP) di ogni riga × quantità, in centesimi. `null` quando non disponibile, quindi ripiega su `originalTotalPrice`.
`currency`	`string`	Codice valuta.
`discountCodes`	`string[]`	Codici sconto accettati sul carrello, ordinati. `[]` quando assenti.
`attributes`	`Record<string, string>`	Attributi del carrello. In sola lettura dall’SDK.

itemCount non è sempre la somma di items. items rispecchia il carrello Shopify reale, incluse le righe add-on che il drawer nasconde, come la shipping protection. itemCount è il numero rivolto all’acquirente che corrisponde al badge del carrello. Per “quante cose ha scelto l’acquirente”, usa itemCount; per iterare sulle righe che il carrello sta renderizzando, usa items.Due cose mancano completamente da items: le righe nascoste con setHidden, e i figli dei bundle, che vengono spostati sul loro anchor. Entrambi contano comunque nei totali del carrello, che arrivano direttamente da 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');
});

Righe del carrello

Ogni voce in items, e l’item su item_added e item_removed:

Campo	Tipo	Descrizione
`key`	`string`	La key Shopify della riga. Passala alle azioni sugli articoli.
`productId`	`number`	ID prodotto Shopify.
`variantId`	`number`	ID variante Shopify.
`handle`	`string`	Handle del prodotto.
`title`	`string`	Titolo visualizzato.
`productTitle`	`string`	Titolo del prodotto senza la variante.
`variantTitle`	`string \| null`	Etichetta della variante, oppure `null`.
`variantOptions`	`Array<{ name, value }>`	Opzioni selezionate, per esempio `[{ name: 'Size', value: 'Medium' }]`. Shopify emette `Title: Default Title` per un prodotto a variante singola.
`quantity`	`number`	Quantità di questa riga.
`linePrice`	`number`	Prezzo della riga, in centesimi.
`finalLinePrice`	`number`	Prezzo della riga dopo gli sconti, in centesimi.
`originalLinePrice`	`number`	Prezzo della riga prima degli sconti, in centesimi.
`compareAtPrice`	`number \| null`	Compare-at della variante (MSRP) per unità, in centesimi. `null` quando assente.
`properties`	`Record<string, string> \| null`	Line item properties.
`internalProperties`	`Record<string, string>`	Overlay solo di rendering da `registerLineTransform`. Mai persistito su Shopify. `{}` quando assente.
`discountAllocations`	`Array<{ title, amount }>`	Sconti applicati a questa riga. `amount` è in centesimi. `[]` quando assenti.
`isGiftCard`	`boolean`	Se la riga è una carta regalo.
`sellingPlan`	`{ id, name } \| null`	Il piano di abbonamento attivo, oppure `null` per un acquisto singolo.
`bundle`	`AftersellCartBundle \| null`	View model del bundle sulla riga anchor; `null` sulle righe non bundle e sui figli.
`metadata`	`Record<string, unknown>`	Dati di arricchimento indicizzati per `id` dell’enricher. `{}` finché un enricher non lo popola.

properties può contenere input fornito dall’acquirente, come il campo di testo personalizzato di un form prodotto. Renderizzalo come testo, mai come HTML grezzo.

Identificare una riga

Usa key per tutto ciò che agisce su una riga, e variantId o productId per tutto ciò che identifica un prodotto:

// ✅ 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);

La stessa variante può apparire su più righe quando le proprietà differiscono. Due tazze incise con testi di incisione diversi sono due righe che condividono un unico variantId. Per questo le azioni accettano key.

Prezzi su una riga

Tre prezzi, facili da confondere:

Vuoi	Usa
Quanto paga l’acquirente per questa riga	`finalLinePrice`
Quanto costava prima degli sconti del carrello	`originalLinePrice`
Il prezzo MSRP barrato, per unità	`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;

Bundle

Quando le righe sono raggruppate in un bundle, la riga anchor porta un oggetto bundle. I figli vengono ripiegati al suo interno e non appaiono più in items per conto proprio. Vedi Raggruppare righe bundle di un’altra app per come si configura il raggruppamento.

Campo	Tipo	Descrizione
`id`	`string`	Identificatore del bundle.
`source`	`'native' \| 'grouped'`	Un bundle nativo Shopify, oppure righe raggruppate da Aftersell.
`memberKeys`	`string[]`	La `key` di ogni riga nel bundle.
`children`	`AftersellBundleChild[]`	I contenuti del bundle.
`displayPrice`	`number`	Il prezzo mostrato per il bundle, in centesimi.

Ogni figlio porta key (null per un 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));

Piani di abbonamento

Il piano attivo di una riga è sellingPlan, oppure null per un acquisto singolo. Per una risposta sull’intero carrello, leggi hasSubscriptionItems invece di scansionare le righe da solo, dato che conta anche le righe add-on che items presenta ma itemCount salta:

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');

I piani disponibili su una riga, quelli nel selettore, non sono sull’oggetto cart. Modellali con registerSubscriptionOptionsTransform e registerDefaultSubscriptionOptionSelector.

Dove andare adesso

Azioni: leggi e modifica il carrello.
Eventi: da dove proviene questo oggetto.
Hook: aggiungi i tuoi dati a una riga con un enricher.
Casi d’uso: soluzioni complete che leggono questi campi.

Per iniziare

Pagina iniziale

Best practice

Upsell post-acquisto

Carrello

Upsell al checkout (Shopify Plus)

Pagina di ringraziamento

Upsell nella pagina prodotto

Rokt Thanks

Strategie

Analisi e monitoraggio

Integrazioni

Aftersell MCP

Fatturazione e account

Risoluzione dei problemi

Il carrello

Righe del carrello

Identificare una riga

Prezzi su una riga

Bundle

Piani di abbonamento

Dove andare adesso

​Il carrello

​Righe del carrello

​Identificare una riga

​Prezzi su una riga

​Bundle

​Piani di abbonamento

​Dove andare adesso

Il carrello

Righe del carrello

Identificare una riga

Prezzi su una riga

Bundle

Piani di abbonamento

Dove andare adesso