Passa al contenuto principale

Personalizzazioni sulle righe

Alcune cose non stanno nel catalogo: un nome da incidere su un anello, un messaggio per un biglietto, un colore che il cliente scrive. Non cambiano la variante, il prezzo o lo stock, ma devono viaggiare con quello che si compra. Per questo ogni riga del carrello e dell'ordine può portare additionalData: coppie di testo e testo.

{ "name": "Anna", "font": "serif" }

Il negozio non legge cosa c'è dentro: lo conserva, lo confronta e lo porta fino all'ordine. Cosa significa lo decide il tuo sito e i tuoi checkout hook.

Una riga è la variante e i suoi dati​

Una riga è una variante insieme ai suoi dati:

  • la stessa variante con gli stessi dati è una sola riga, e la quantità si somma (l'ordine delle chiavi non conta);
  • la stessa variante con altri dati è un'altra riga: due anelli con due nomi sono due righe;
  • nessun dato, null e {} sono la stessa cosa: una riga senza dati, esattamente come erano tutte prima.

Lo stock invece è quello della variante: le quantità di tutte le sue righe si sommano, e se insieme sono più di quello che c'è, ognuna di quelle righe risulta non disponibile. Lo stesso vale per i più venduti: si contano per variante, qualunque siano i dati.

Limiti​

CosaLimite
Chiavifino a 20
Una chiaveda 1 a 64 caratteri
Un valoretesto, fino a 500 caratteri

Quello che non è testo, o supera un limite, viene rifiutato con un 400 e non si salva niente.

Dove vanno i dati​

  1. Il carrello. Il carrello dell'ospite (nel browser) e quello del cliente li conservano con la riga. Quando un ospite accede, le righe vengono unite al carrello del cliente con i loro dati: una riga che il cliente ha già, con gli stessi dati, si somma; un'altra è una riga nuova.
  2. Il checkout. Il preventivo e il pagamento prendono le righe con i loro dati, e i checkout hook ricevono additionalData su ogni riga (null quando non ne ha). Un'operazione di un hook che punta a una riga la indica per variante e dati quando la variante è nel carrello con dati diversi; la stessa variante due volte con gli stessi dati viene rifiutata con CART_DUPLICATE_ITEMS.
  3. Stripe. La riga nella pagina di pagamento di Stripe mostra i dati dopo le opzioni, come chiave: valore, così il cliente legge cosa sta pagando.
  4. L'ordine. Ogni riga dell'ordine conserva i dati con cui è stata comprata. Due righe della stessa variante con dati diversi restano due righe dell'ordine. Le leggi nelle API e negli eventi degli ordini, e l'admin le mostra nella colonna Dettagli degli articoli di un ordine, anche per gli ordini che arrivano da Stripe.

Dall'SDK​

Con l'SDK commerce i dati vanno nella riga che aggiungi, e la stessa coppia di variante e dati indica la riga quando la cambi o la togli:

await commerce.cart.add({
variantId,
priceId,
quantity: 1,
additionalData: { name: "Anna", font: "serif" },
});

// la riga di quella variante con quei dati
await commerce.cart.setQuantity({ variantId, additionalData: { name: "Anna", font: "serif" } }, 2);
await commerce.cart.remove({ variantId, additionalData: { name: "Anna", font: "serif" } });

Un testo al posto di un oggetto (cart.remove(variantId)) indica la riga di quella variante senza dati, come è sempre stato. L'hook React (useCart, vedi React) prende e restituisce gli stessi dati.

Dalle API​

POST /cart, POST /cart/merge e POST /cart/total prendono additionalData su ogni riga, e il carrello risponde con lo stesso campo. PATCH e DELETE di /cart/{id} agiscono sulla riga con quell'id, cioè quella con i suoi dati. Il preventivo e il pagamento dell'API di checkout lo prendono sulle righe, come dicono le pagine del riferimento API.