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,
nulle{}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
| Cosa | Limite |
|---|---|
| Chiavi | fino a 20 |
| Una chiave | da 1 a 64 caratteri |
| Un valore | testo, 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
- 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.
- Il checkout. Il preventivo e il pagamento prendono le righe con i loro dati, e i checkout hook ricevono
additionalDatasu ogni riga (nullquando 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 conCART_DUPLICATE_ITEMS. - 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. - 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.