Next.js E-commerce
Come creare un carrello e integrare Stripe Checkout con Next.js
Implementa in Next.js carrelli anonimi e dei clienti, prezzi gestiti dal server, Stripe Checkout, webhook firmati, ordini idempotenti e validazione delle scorte.
Il carrello registra l'intenzione di acquisto. Non autorizza un prezzo, non riserva automaticamente le scorte e non dimostra che il pagamento sia completato.
Scegli identità e durata del carrello
Crea un token casuale per il carrello degli acquirenti anonimi e salvalo in un cookie sicuro HTTP-only. Il database gestisce carrello, ID delle varianti nelle righe, quantità, timestamp e stato. Dopo l'accesso, associalo o uniscilo al cliente secondo regole esplicite.
Imposta una scadenza per inattività e decidi se i carrelli passati al checkout diventano istantanee immutabili. Non conservare l'intero carrello o i prezzi ufficiali in un cookie leggibile dal browser, dove clienti ed estensioni possono modificarli.
Valida ogni modifica al carrello
Un'azione di aggiunta accetta ID della variante e quantità, risolve il carrello dal token controllato dal server, verifica che la variante sia attiva, applica i limiti di quantità ed esegue l'upsert della riga. Non accetta mai dal browser appartenenza dell'account, prezzo dello SKU o valuta.
Restituisci un errore previsto per varianti non valide o indisponibili. Rivalida la vista del carrello dopo la scrittura, così l'utente vede il proprio aggiornamento. I controlli di autorizzazione e appartenenza devono stare nell'azione anche quando l'interfaccia mostra solo controlli validi.
"use server";
export async function addToCart(variantId: string, quantity: number) {
const cart = await requireCart();
const variant = await getPurchasableVariant(variantId);
if (!variant) return { error: "Variant unavailable" };
await upsertCartLine(cart.id, variant.id, clampQuantity(quantity));
updateTag("cart:" + cart.id);
}Unisci i carrelli anonimi e dei clienti
All'accesso, carica entrambi i carrelli in un'unica transazione sul server. Combina varianti identiche fino ai limiti di acquisto, conserva le righe distinte valide e segnala articoli rimossi o modificati. Contrassegna il carrello anonimo come unito, così ripetere la stessa richiesta non può duplicare le quantità.
Non scegliere senza avvisare il carrello più costoso o più recente. Il prodotto deve definire se prevale il carrello del cliente, se i carrelli vengono uniti o se sceglie l'acquirente. Verifica il comportamento con più schede e callback di accesso ripetuti.
Ricalcola i prezzi prima di Checkout
Carica sul server ogni variante attiva e il prezzo corrente, applica sconti validati, calcola dati fiscali e opzioni di spedizione, poi crea un'istantanea dell'ordine in attesa. Se prezzo o disponibilità sono cambiati, restituisci il carrello aggiornato per una conferma esplicita, anziché addebitare un importo diverso senza avvisare.
Crea le righe Stripe dai record del server. Aggiungi l'ID dell'ordine in attesa ai metadati e usa una chiave di idempotenza stabile per un checkout ripetuto quando il business richiede una sola operazione sul provider.
Conferma il pagamento tramite webhook
L'URL di successo indica il ritorno da Checkout; non dimostra il regolamento del pagamento. Verifica la firma del webhook sul corpo originale della richiesta, individua l'ordine in attesa da metadati attendibili e registra l'evento Stripe con un vincolo di unicità.
Crea o contrassegna l'ordine definitivo una sola volta, poi metti in coda email di conferma ed evasione. Un evento duplicato deve restituire successo senza ripetere questi effetti. Una sessione scaduta può liberare le prenotazioni e riportare il carrello a uno stato modificabile.
export async function POST(request: Request) {
const rawBody = await request.text();
const signature = request.headers.get("stripe-signature");
const event = stripe.webhooks.constructEvent(
rawBody,
signature,
process.env.STRIPE_WEBHOOK_SECRET,
);
await processCheckoutEventOnce(event);
return new Response(null, { status: 200 });
}Proteggi le letture di carrelli e ordini
L'accesso al carrello anonimo richiede il token non indovinabile emesso dal server. Carrelli e ordini dei clienti richiedono il proprietario autenticato. Le pagine di conferma devono caricare l'ordine usando sia il riferimento sicuro per uso pubblico sia il contesto del proprietario, senza esporre ID sequenziali del database.
Restituisci DTO limitati ai Client Components. Oggetti del provider di pagamento, campi interni antifrode, payload dei webhook ed errori del database rimangono sul server. I log devono usare identificatori di ordini ed eventi senza stampare inutilmente dati di pagamento o indirizzi.
Verifica manomissioni, nuovi tentativi e scadenze
Modifica la variante e la quantità inviate e il prezzo visualizzato; ripeti le azioni di aggiunta e unione; consegna due volte un webhook e invia eventi fuori ordine; fai scadere Checkout; rimuovi scorte durante il pagamento; richiedi l'ordine di un altro cliente. Ogni esito deve essere sicuro e spiegabile.
Distribuisci la compilazione di produzione su Adios con riferimenti ai segreti di Stripe e del database. Verifica la route HTTPS generata in modalità test, esamina i log dell'ambiente di esecuzione e registra il webhook stabile sul dominio personalizzato solo quando il rilascio risulta sano.