Costruisci uno storefront

Questa guida mostra il flusso principale di uno storefront. Tutti gli endpoint sono sotto /api/v1 e usano la chiave publishable (o il dominio del negozio).

Importi come stringhe. I campi decimali di prodotti, carrello, checkout e ordini (price, unit_price, subtotal, total…) arrivano come stringhe ("1199.00"). Convertili prima di fare calcoli: in JavaScript "10.00" + "5.00" concatena invece di sommare. Per i soldi usa una libreria decimale o lavora in centesimi.

1. Catalogo & ricerca

# lista prodotti con filtri
curl "$BASE/api/v1/products?category_id=<id>&min_price=500&sort=-created_at&page=1&page_size=24"
# dettaglio per slug
curl "$BASE/api/v1/products/<slug>?lang=it"
# ricerca full-text con facet
curl "$BASE/api/v1/search?q=iphone&page=1"
# categorie (albero), brand
curl "$BASE/api/v1/categories?tree=true"

I filtri min_price, max_price e l’ordinamento sort=price / sort=-price lavorano sul prezzo effettivo (saldo attivo e prezzo speciale), e meta.total coincide sempre con le righe filtrate. in_stock=true tiene solo i prodotti con una variante acquistabile.
Nella lista, sale_price è il saldo attivo della variante oppure lo speciale, se più basso; null senza sconti attivi.

Nel dettaglio prodotto (GET /products/{slug}) ci sono due campi nuovi:

Campo	Significato
`special_price`	prezzo speciale attivo per un ospite, a livello di prodotto. Mostralo come prezzo scontato quando è sotto il prezzo della variante
`stock_status_name`	testo di disponibilità scelto dal negozio (per esempio «In arrivo»), già nella lingua richiesta: mostralo quando la variante è esaurita

{
  "data": {
    "slug": "iphone-17-pro-256gb",
    "special_price": "1149.00",
    "stock_status_name": "In arrivo",
    "variants": [
      {
        "sku": "IPH17P-256-NERO",
        "price": "1249.00",
        "compare_at_price": "1349.00",
        "sale_price": null,
        "stock": 0,
        "track_inventory": true,
        "allow_backorder": false
      }
    ]
  }
}

Nelle varianti sale_price è null fuori dalla finestra del saldo (sale_start–sale_end). Una variante con track_inventory: false è acquistabile anche a giacenza 0.

2. Carrello

Il carrello funziona per ospiti (con un token di sessione) e per clienti loggati.

# crea/aggiorna carrello, aggiungi una variante
curl -X POST "$BASE/api/v1/cart/items" -H "Content-Type: application/json" \
  -d '{"variant_id":"<id>","quantity":1}'
# leggi il carrello (righe, prezzi applicati, regole del negozio)
curl "$BASE/api/v1/cart"

Carrello cross-origin / headless. Il carrello ospite è legato a un token di sessione, restituito nel campo session_token della risposta. Se il tuo storefront gira su un dominio diverso dall’API (es. xxxx.com → api.vellaro.io), il cookie cx_cart (SameSite=Lax) non viaggia cross-site: salva session_token lato client (es. localStorage) e rimandalo su ogni chiamata al carrello e al checkout come header X-Cart-Token. Così il carrello persiste ovunque e si ripristina al ritorno (TTL 7 giorni). Se sei same-origin, basta il cookie e l’header è opzionale.

# la risposta contiene { "data": { "session_token": "…", "items": [...] } }
# → salva session_token e rimandalo su ogni chiamata carrello + checkout:
curl -X POST "$BASE/api/v1/cart/items" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "X-Cart-Token: <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"variant_id":"<id>","quantity":1}'

Il carrello all’accesso

Quando l’ospite accede, il suo carrello si unisce a quello dell’account alla prima chiamata autenticata al carrello, o al checkout, che porta ancora il token ospite (X-Cart-Token o cookie cx_cart):

lo stesso articolo si somma, ma mai oltre le scorte disponibili;
gli articoli non più in vendita restano fuori;
il carrello ospite viene eliminato, e lo stesso token non si unisce due volte.

Cosa fare nel client:

continua a mandare X-Cart-Token anche dopo il login;
ricarica il carrello subito dopo l’accesso (password, social o registrazione), così il badge e il cassetto mostrano gli articoli uniti;
quando la risposta del carrello ha user_id valorizzato, smetti di usare il token ospite;
all’uscita togli dallo schermo il carrello dell’account.

Il prezzo da mostrare è `unit_price`

Ogni riga porta il prezzo davvero applicato, che tiene già conto di saldo, prezzo speciale, sconto a quantità e gruppo del cliente: unit_price, con line_total = unit_price × quantity. Mostra quello. variant.price e variant.sale_price sono prezzi di listino e non vanno usati per righe e totali.

{
  "data": {
    "session_token": "kJ8x...",
    "items": [
      {
        "id": "e5f6a7b8-0000-4000-8000-abcdefabcdef",
        "variant_id": "11112222-3333-4444-8555-666677778888",
        "quantity": 2,
        "unit_price": "1149.00",
        "line_total": "2298.00",
        "variant": { "sku": "IPH17P-256-NERO", "price": "1249.00", "sale_price": null }
      }
    ],
    "subtotal": "2298.00",
    "item_count": 2,
    "min_order_total": "20.00",
    "guest_checkout_enabled": true
  },
  "meta": null,
  "error": null,
  "error_code": null
}

Le regole del negozio

Il carrello espone le regole che il checkout applica, così puoi mostrarle prima del pagamento:

min_order_total: ordine minimo sul subtotal (zero = nessun minimo). Sotto la soglia, mostra quanto manca e disattiva il pulsante di pagamento.
guest_checkout_enabled: con false il negozio accetta ordini solo da clienti registrati. Chiedi login o registrazione prima del checkout.

3. Checkout & pagamento

Prendi i metodi di pagamento sempre dalla lista pubblica: il checkout accetta solo quelli. Ogni metodo è un code stabile (stripe, paypal, pokpay, paysera, bank_transfer, cod) da tradurre nel client.

# metodi di pagamento attivi nel negozio
curl "$BASE/api/v1/settings/payment-methods"
# crea l'ordine (ospite): manda sempre payment_method preso dalla lista
curl -X POST "$BASE/api/v1/checkout" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "X-Cart-Token: <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "cliente@example.com",
    "payment_method": "stripe",
    "coupon_code": "ESTATE10",
    "voucher_code": "REGALO50",
    "locale": "it",
    "shipping_address": {
      "first_name": "Mario", "last_name": "Rossi",
      "address_line1": "Via Roma 12", "city": "Milano",
      "postal_code": "20121", "country": "IT", "phone": "+39 333 1234567"
    }
  }'

La risposta di checkout indica il flusso di pagamento (Stripe, PayPal, PokPay, Paysera, contrassegno, bonifico): alcuni restituiscono un client_secret/redirect da completare lato client, altri confermano subito. Un ordine online mai pagato si può riaprire con POST /orders/{order_id}/pay («Paga ora»): stessa risposta del checkout, stesso ordine. Vedi la API Reference per lo schema esatto di POST /checkout.

Errori delle regole del negozio

`error_code`	HTTP	Quando	`data`
`checkout.min_order_not_met`	422	subtotale sotto l’ordine minimo	`min_order_total`, `subtotal`, `currency`
`checkout.login_required`	401	il negozio non accetta ordini da ospite	—
`checkout.payment_method_disabled`	422	metodo spento dal negozio (anche se omesso: il predefinito è `stripe`)	`payment_method`

Lo sconto di un coupon non supera mai il subtotale, e un coupon «spedizione gratuita» azzera la spedizione.

Buono regalo

Il cliente inserisce il codice del buono e tu lo mandi in voucher_code. Il saldo paga il totale dopo il coupon, spedizione compresa.

Il saldo viene prenotato quando nasce l’ordine e diventa definitivo al pagamento: due checkout non possono spendere lo stesso saldo.
Il saldo torna sul buono quando il tentativo di pagamento è chiuso davvero (pagamento annullato, tentativo sostituito da un nuovo checkout, ordine annullato dal negozio) e, per un ordine pagato, con il rimborso totale o l’annullo. Una carta rifiutata non libera il buono, perché lo stesso pagamento si può ritentare.
Se il buono copre tutto il totale, la risposta ha payment_method: "voucher" e nessun dato di gateway: l’ordine è già pagato, vai alla pagina di conferma.
La risposta porta voucher_code, voucher_amount (importo usato) e voucher_remaining (saldo che resta, da mostrare al cliente).
Il buono non paga un abbonamento.

`error_code`	HTTP	Significato
`voucher.not_found`	404	codice inesistente
`voucher.inactive`	422	buono disattivato
`voucher.reserved`	422	il saldo è tenuto da un altro ordine online ancora in attesa di pagamento
`voucher.exhausted`	422	buono già speso del tutto
`voucher.not_with_subscription`	422	il buono non si usa con `subscribe_recurring_id`
`voucher.insufficient_balance`	409	solo su «Paga ora»: il saldo nel frattempo è stato speso altrove

4. Ordini & tracking

# ordini del cliente (autenticato)
curl "$BASE/api/v1/orders" -H "Authorization: Bearer $TOKEN"
# tracking di un ordine
curl "$BASE/api/v1/orders/<id>"

La cronologia (history) che vede il cliente è filtrata:

contiene solo cambi di stato (event_type: "status_change") e note pubbliche (event_type: "note"); pagamenti, rimborsi, spedizioni ed email restano allo staff;
una riga di stato scritta dal sistema ha comment: null: traduci lo status nel client. Il commento resta solo se lo ha scritto lo staff e lo ha reso pubblico;
una nota ha status: null.

{
  "history": [
    { "event_type": "status_change", "status": "processing", "comment": null, "created_at": "2026-10-04T09:31:12Z" },
    { "event_type": "status_change", "status": "shipped", "comment": "Consegna prevista venerdì", "created_at": "2026-10-05T08:15:00Z" },
    { "event_type": "note", "status": null, "comment": "Abbiamo aggiunto un campione omaggio", "created_at": "2026-10-05T08:20:00Z" }
  ]
}

payment_status può valere anche partially_refunded; payment_method può valere voucher.

5. Abbonamenti

Un prodotto può avere piani ricorrenti (recurrings nel dettaglio prodotto). Il cliente si abbona al checkout con subscribe_recurring_id (serve il login e payment_method: "stripe").

All’acquisto si paga il prezzo del prodotto; ai rinnovi il prezzo del piano (price).
La «prova» sposta solo il primo rinnovo: arriva dopo trial_length unità di trial_frequency invece che dopo un intervallo. trial_price non è applicato.
billing_interval dice ogni quante frequency si rinnova; billing_charges è il numero di addebiti in tutto, acquisto compreso (0 = fino all’annullo).

In GET /account/subscriptions lo stato può essere active, trialing, past_due, paused, canceled oppure completed: concluso, tutte le rate addebitate e next_billing_date: null. Su un abbonamento completed nascondi il pulsante di annullo: POST /account/subscriptions/{id}/cancel risponde 409 subscription.already_completed.

Consulente rapido: la lista completa di parametri, corpi e risposte è nella API Reference, generata dallo schema OpenAPI live — quindi sempre allineata alla produzione.

Campagne

Un link di campagna ha la forma https://<negozio>/…?cmp=<codice>. Quando lo storefront trova il parametro cmp, chiama una volta per browser:

curl -X POST "$BASE/api/v1/marketing/track" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "Content-Type: application/json" \
  -d '{"code":"AUTUNNO26"}'
# → { "data": { "counted": true }, ... }

La stessa visita conta una volta ogni 30 minuti (counted: false per le successive) e un codice sconosciuto risponde 200 con counted: false. Limite: 30 richieste al minuto per IP.

Aspetto & configurazione

GET /settings/store-info — nome, contatti, social, appearance (logo, colori) per brandizzare il tuo frontend come il negozio. Contiene anche:
- catalog.items_per_page (prodotti per pagina, null = scegli tu) e catalog.default_sort (ordinamento predefinito delle categorie, già nella sintassi di GET /products?sort=, oppure null);
- seo.meta_title_default e seo.meta_description_default: titolo e descrizione per le pagine senza meta propri (stringa vuota = non impostati).
GET /banners, GET /information/<slug> — contenuti CMS e hero.
GET /languages, GET /currencies — per selettori lingua/valuta.

Inizia

Guide

AI & MCP

Costruisci uno storefront

1. Catalogo & ricerca

2. Carrello

Il carrello all’accesso

Il prezzo da mostrare è `unit_price`

Le regole del negozio

3. Checkout & pagamento

Errori delle regole del negozio

Buono regalo

4. Ordini & tracking

5. Abbonamenti

Campagne

Aspetto & configurazione

1. Catalogo & ricerca

2. Carrello

Il carrello all’accesso

Il prezzo da mostrare è unit_price

Le regole del negozio

3. Checkout & pagamento

Errori delle regole del negozio

Buono regalo

4. Ordini & tracking

5. Abbonamenti

Campagne

Aspetto & configurazione

Il prezzo da mostrare è `unit_price`