Variante

La Variante è l'unità atomica e operativa di Webround Commerce. Se il Prodotto è il template generale, la Variante è la sua declinazione commerciale specifica — e l'unico elemento che possiede un'esistenza fisica in magazzino, un prezzo e può essere aggiunta al carrello.

Senza una Variante, un prodotto non può essere né prezzato né venduto.

Identità e Navigazione

Ogni variante possiede attributi unici per la sua identificazione e navigazione nel frontend:

Proprietà	Tipo	Descrizione
id	`string` (UUID)	Identificativo univoco della variante.
name	`string`	Nome specifico della declinazione (es. "Nike Pegasus 41 - Total White").
slug	`string`	Parte "friendly-url" che identifica univocamente la variante nel sito.
isFavourite	`boolean`	Se `true`, questa variante viene caricata per prima sulla pagina prodotto.
productId	`string` (UUID)	Riferimento al Product padre.
availability	`string`	Stato di disponibilità: `available`, `low_availability`, `not_available`.

URL Structure: tuodominio.com/product/[slug]

Ereditarietà e Sovrascrittura

La gestione delle Varianti si basa su un sistema di ereditarietà dal prodotto padre. Per ogni campo soggetto a ereditarietà puoi scegliere tra due modalità:

Ereditarietà (Flag Attivo): La variante eredita automaticamente le impostazioni del prodotto. Elementi aggiunti a livello di variante si sommano a quelli del prodotto.
Sovrascrittura (Flag Disattivato): La variante interrompe il legame con il prodotto per quel campo specifico e lo ridefinisce interamente.

Regola di integrità: Non è possibile ricollegare manualmente elementi che la variante sta già ereditando dal prodotto. Per definire un sottoinsieme specifico (es. limitare la variante a uno solo dei tre corrieri del prodotto) devi disattivare l'ereditarietà per quel campo e procedere alla configurazione manuale.

Proprietà	Tipo	Descrizione
inheritAssets	`boolean`	Se `true`, utilizza gli asset del prodotto padre.
inheritAttributes	`boolean`	Se `true`, utilizza gli attributi del prodotto padre.
inheritTagValues	`boolean`	Se `true`, eredita i tag dal prodotto padre.
inheritShipping	`boolean`	Se `true`, eredita metodi e zone di spedizione dal prodotto padre.
inheritTaxZones	`boolean`	Se `true`, eredita le tax zone dal prodotto padre.
inheritDisableCoupons	`boolean`	Se `true`, eredita le regole di disabilitazione coupon dal prodotto padre.

Campi soggetti a ereditarietà: Asset, Tag e Attributi, Dimensioni e Peso del pacco, Logistica (metodi di spedizione, zone di spedizione, tax zone), Impostazioni Coupon.

Gestione Operativa e Logistica

La variante incorpora tutte le informazioni operative necessarie al checkout e alla sincronizzazione con sistemi esterni (ERP/Logistica):

Proprietà	Tipo	Descrizione
sku	`string`	Codice identificativo commerciale univoco (es. "NIK-A6B512-283BBA").
ean	`string`	Barcode standard internazionale (EAN).
mpn	`string`	Manufacturer Part Number (codice produttore).
quantity	`number`	Quantità attualmente disponibile a magazzino.
allowBackorder	`boolean`	Se `true`, permette l'acquisto anche se lo stock è esaurito (backorder).
backorderDays	`number`	Giorni stimati per il rifornimento in caso di backorder.
maxOrderQuantity	`number`	Limite massimo di pezzi acquistabili in un singolo ordine.
allowFreeShipping	`boolean`	La variante è idonea alla spedizione gratuita secondo le regole generali.
forceFreeShipping	`boolean`	Se `true`, forza la spedizione gratuita indipendentemente dalle regole del carrello.

Opzioni

Le Opzioni (es. "Taglia") si definiscono a livello di Prodotto, ma è a livello di Variante che prendono vita tramite la mappa options.

Proprietà	Tipo	Descrizione
options	`Object`	Mappa delle opzioni selezionate: `{ "ID_OPZIONE": "ID_VALORE_OPZIONE" }`.

Durante la generazione automatica delle varianti, il sistema incrocia le opzioni definite sul prodotto e assegna automaticamente i tag corrispondenti alla variante, rendendola immediatamente filtrabile.

Filtrabilità

Se crei un'opzione "Taglia Scarpe" con valori 40, 41, 42… e la associ alla variante tramite la generazione automatica, la variante risulterà già taggata con tutte le taglie. Impostando il Tag come filtrabile, i clienti potranno filtrare per taglia nel frontend.

Strategia di Prezzo (Multi-Price & Multi-Currency)

Una variante non è limitata a un singolo prezzo. Webround permette flessibilità totale tramite l'array prices:

Proprietà	Tipo	Descrizione
prices	`Price[]`	Array di prezzi applicabili a questa variante.
priceRanges	`PriceRange[]`	Intervalli di prezzo (min/max) calcolati sulle opzioni della variante. Usati per il rendering nelle card prodotto.

Modelli di prezzo supportati

Prezzo Una Tantum (cadence: "once"): La vendita classica.
Abbonamenti: Prezzi con frequenza (daily, monthly, yearly, ecc.). La stessa variante può essere venduta sia come acquisto singolo che come sottoscrizione.

Non è possibile definire due prezzi con la stessa combinazione di cadence e currencyCode.

Prezzo Comparativo (Sconto Visivo)

Il Compare Price è il prezzo originale mostrato barrato accanto al prezzo attuale. Gestisce la percezione dello sconto direttamente nella scheda prodotto.

Tasse: Netto vs Lordo

Il consiglio tecnico è ragionare sempre sul prezzo Netto. L'aliquota fiscale viene determinata dalla Tax Zone (o da Stripe Tax) in base alla posizione del cliente. Prezzi lordi sono corretti solo per il mercato principale; per vendite multinazionali, il calcolo netto + tax zone è l'unica via per una contabilità corretta.

Sconti per Quantità (Tier Pricing)

Ogni prezzo può includere una quantityTable che automatizza la scontistica basata sul volume. Il prezzo unitario viene ricalcolato in tempo reale al variare della quantità nel carrello.

Tag e Attributi

Proprietà	Tipo	Descrizione
tags	`Tag[]`	Tag specifici per la variante (es. Colore, Taglia).
attributes	`Attribute[]`	Attributi specifici per la variante.
assets	`Asset[]`	Risorse multimediali specifiche per questa variante.

Marketing e Promozioni

Esclusione Promozioni: È possibile collegare specifiche promozioni da cui la variante deve essere esclusa.
Coupon: La variante può ereditare le regole coupon del prodotto o seguire logiche indipendenti (controllato da inheritDisableCoupons).

Definizione completa

interface Variant {
  // Identità
  id: string;
  name: string;
  slug: string;
  isFavourite: boolean;
  productId: string;
  availability: "available" | "low_availability" | "not_available";
  metadata: Record<string, unknown>;

  // Ereditarietà
  inheritAssets: boolean;
  inheritAttributes: boolean;
  inheritTagValues: boolean;
  inheritShipping: boolean;
  inheritTaxZones: boolean;
  inheritCoupon: boolean;

  // Operativo / Magazzino
  sku: string;
  ean: string;
  mpn: string;
  quantity: number;
  allowBackorder: boolean;
  backorderDays: number;
  maxOrderQuantity: number;
  allowFreeShipping: boolean;
  forceFreeShipping: boolean;

  // Opzioni
  options: Record<string, string>; // { optionId: optionValueId }

  // Prezzi
  prices: Price[];
  priceRanges: PriceRange[];

  // Relazioni
  tags: Tag[];
  attributes: Attribute[];
  assets: Asset[];
}

Price

Rappresenta un prezzo puntuale della variante.

Proprietà	Tipo	Descrizione
id	`string` (UUID)	Identificativo univoco del prezzo.
amount	`number`	Valore nominale del prezzo.
netAmount	`number`	Prezzo netto unitario.
grossAmount	`number`	Prezzo lordo unitario (ivato).
netCompare	`number`	Prezzo di confronto netto (prezzo originale).
grossCompare	`number`	Prezzo di confronto lordo (prezzo originale ivato).
currencyCode	`string`	Codice valuta ISO (es. `EUR`).
cadence	`string`	Frequenza di pagamento (es. `once`).
isDefault	`boolean`	Indica se è il prezzo principale per la valuta corrente.
externalId	`string`	ID prodotto Stripe o sistema esterno.
quantityTable	`QuantityTable` \| `null`	Tabella per sconti a scaglioni (tier pricing).

Esempio

{
    "id": "3ec67ca3-1563-4161-b90e-e144d5a8f206",
    "amount": 139,
    "netAmount": 139,
    "grossAmount": 169.58,
    "netCompare": 0,
    "grossCompare": 0,
    "currencyCode": "EUR",
    "cadence": "once",
    "isDefault": true,
    "externalId": "",
    "quantityTable": null,
    "rate": 22
}

PriceRange

Descrive l'escursione di prezzo calcolata sulle opzioni della variante. Utilizzato principalmente per il rendering nelle card prodotto.

Proprietà	Tipo	Descrizione
currencyCode	`string`	Codice valuta ISO (es. `EUR`).
cadence	`string`	Frequenza di pagamento (es. `once`).
netMin	`number`	Prezzo minimo netto.
netMax	`number`	Prezzo massimo netto.
grossMin	`number`	Prezzo minimo lordo (IVA inclusa).
grossMax	`number`	Prezzo massimo lordo.
compareNetMin	`number`	Prezzo di confronto minimo netto.
compareNetMax	`number`	Prezzo di confronto massimo netto.
compareGrossMin	`number`	Prezzo di confronto minimo lordo.
compareGrossMax	`number`	Prezzo di confronto massimo lordo.
rate	`number`	Aliquota IVA applicata (es. `22`).

Visualizzazione Sconti

Per mostrare un badge "Promo" o il prezzo barrato, confronta grossMin con compareGrossMin. Se compareGrossMin > grossMin, la variante è in offerta.

QuantityTable (Tier Pricing)

Proprietà	Tipo	Descrizione
min	`number`	Quantità minima per attivare lo scaglione.
max	`number` \| `null`	Quantità massima (`null` = illimitato).
discountType	`string`	Tipo di sconto: `percentage` o `fixed`.
discountValue	`number`	Valore dello sconto.
rounding	`string` \| `null`	Arrotondamento finale del prezzo (es. `"99"` → il prezzo chiude con `,99`).

Esempio

[
    { "min": 1,  "max": 4,    "discountType": "percentage", "discountValue": 5,  "rounding": "00" },
    { "min": 5,  "max": 9,    "discountType": "percentage", "discountValue": 10, "rounding": "00" },
    { "min": 10, "max": null, "discountType": "percentage", "discountValue": 20, "rounding": "99" }
]

Calcolo del Prezzo

Il prezzo finale viene calcolato applicando lo sconto del tier corrispondente al valore amount (o grossAmount) della variante. Se la quantità nel carrello cambia, il prezzo unitario viene ricalcolato in tempo reale.

Esempio di oggetto completo

{
    "id": "08d2a27f-19b4-41aa-b380-ddebb01ac6d4",
    "name": "Nike Pegasus - Verde",
    "slug": "nike-pegasus-verde-704a84",
    "metadata": {},
    "isFavourite": true,
    "productId": "6cd8ad36-21eb-4c1c-b554-58315b70fed3",
    "availability": "available",
    "inheritAssets": true,
    "inheritAttributes": true,
    "inheritTagValues": true,
    "inheritShipping": true,
    "inheritTaxZones": true,
    "inheritCoupon": false,
    "sku": "NIK-A6B512-283BBA",
    "ean": "",
    "mpn": "",
    "quantity": 29,
    "allowBackorder": false,
    "backorderDays": 0,
    "maxOrderQuantity": 30,
    "allowFreeShipping": false,
    "forceFreeShipping": false,
    "options": {
        "2d395c94-552a-4dbf-95de-230f94e0844c": "eccd7e69-2aa2-4bbc-92ef-75a07f0a01e6"
    },
    "prices": [
        {
            "id": "3ec67ca3-1563-4161-b90e-e144d5a8f206",
            "amount": 139,
            "netAmount": 139,
            "grossAmount": 169.58,
            "netCompare": 0,
            "grossCompare": 0,
            "currencyCode": "EUR",
            "cadence": "once",
            "isDefault": true,
            "externalId": "",
            "quantityTable": null,
            "rate": 22
        }
    ],
    "priceRanges": [
        {
            "currencyCode": "EUR",
            "cadence": "once",
            "netMin": 139,
            "netMax": 139,
            "grossMin": 169.58,
            "grossMax": 169.58,
            "compareNetMin": 0,
            "compareNetMax": 0,
            "compareGrossMin": 0,
            "compareGrossMax": 0,
            "rate": 22
        }
    ],
    "tags": [
        {
            "id": "1c0edb9e-c2fd-41eb-960a-f17723beeb52",
            "name": "Colore",
            "filterable": true,
            "type": "string",
            "values": [
                { "id": "9538621f-c258-4793-87d5-7a112e20a3e1", "value": "Verde", "alias": "" }
            ]
        }
    ],
    "assets": [
        {
            "id": "96228bd5-5dd5-417c-9c74-4f4df3f53efe",
            "url": "https://webrounddev.b-cdn.net/.../nike-pegasus-verde.png",
            "type": "image",
            "position": 0,
            "thumbnail": "",
            "inherited": false
        }
    ],
    "attributes": []
}

Gestione UI

Nelle card prodotto usa priceRanges per mostrare il prezzo e assets per l'immagine corretta in base alla variante selezionata. La variante corretta viene identificata incrociando le selezioni dell'utente (le options) con le varianti del prodotto.

Identità e Navigazione​

Ereditarietà e Sovrascrittura​

Gestione Operativa e Logistica​

Opzioni​

Strategia di Prezzo (Multi-Price & Multi-Currency)​

Modelli di prezzo supportati​

Prezzo Comparativo (Sconto Visivo)​

Tasse: Netto vs Lordo​

Sconti per Quantità (Tier Pricing)​

Tag e Attributi​

Marketing e Promozioni​

Definizione completa​

Price​

Esempio​

PriceRange​

QuantityTable (Tier Pricing)​

Esempio​

Esempio di oggetto completo​

Identità e Navigazione

Ereditarietà e Sovrascrittura

Gestione Operativa e Logistica

Opzioni

Strategia di Prezzo (Multi-Price & Multi-Currency)

Modelli di prezzo supportati

Prezzo Comparativo (Sconto Visivo)

Tasse: Netto vs Lordo

Sconti per Quantità (Tier Pricing)

Tag e Attributi

Marketing e Promozioni

Definizione completa

Price

Esempio

PriceRange

QuantityTable (Tier Pricing)

Esempio

Esempio di oggetto completo