Variant
The Variant is the atomic and operational unit of Webround Commerce. While the Product serves as the general template, the Variant is its specific commercial declination — and the only element that possesses a physical existence in the warehouse, a price, and the ability to be added to the cart.
Without a Variant, a product can neither be priced nor sold.
Identity and Navigation
Each variant possesses unique attributes for its identification and navigation within the frontend:
| Property | Type | Description |
|---|---|---|
| id | string (UUID) | Unique identifier of the variant. |
| name | string | Specific name of the declination (e.g., "Nike Pegasus 41 - Total White"). |
| slug | string | The "friendly-url" part that uniquely identifies the variant on the site. |
| isFavourite | boolean | If true, this variant is loaded first on the product page. |
| productId | string (UUID) | Reference to the parent Product. |
| availability | string | Availability status: available, low_availability, not_available. |
URL Structure: yourdomain.com/product/[slug]
Inheritance and Overriding
Variant management is based on a system of inheritance from the parent product. For each field subject to inheritance, you can choose between two modes:
- Inheritance (Flag Active): The variant automatically inherits the product's settings. Elements added at the variant level are added to those of the product.
- Overriding (Flag Inactive): The variant breaks the link with the product for that specific field and redefines it entirely.
Integrity Rule: It is not possible to manually relink elements that the variant is already inheriting from the product. To define a specific subset (e.g., limiting the variant to only one of the product's three carriers), you must disable inheritance for that field and proceed with manual configuration.
| Property | Type | Description |
|---|---|---|
| inheritAssets | boolean | If true, uses the parent product's assets. |
| inheritAttributes | boolean | If true, uses the parent product's attributes. |
| inheritTagValues | boolean | If true, inherits tags from the parent product. |
| inheritShipping | boolean | If true, inherits shipping methods and zones from the parent product. |
| inheritTaxZones | boolean | If true, inherits tax zones from the parent product. |
| inheritDisableCoupons | boolean | If true, inherits coupon disabling rules from the parent product. |
Fields subject to inheritance: Assets, Tags and Attributes, Package Dimensions and Weight, Logistics (shipping methods, shipping zones, tax zones), Coupon Settings.
Operational and Logistic Management
The variant incorporates all the operational information necessary for checkout and synchronization with external systems (ERP/Logistics):
| Property | Type | Description |
|---|---|---|
| sku | string | Unique commercial identifier code (e.g., "NIK-A6B512-283BBA"). |
| ean | string | International standard barcode (EAN). |
| mpn | string | Manufacturer Part Number. |
| quantity | number | Quantity currently available in stock. |
| allowBackorder | boolean | If true, allows purchase even if stock is exhausted (backorder). |
| backorderDays | number | Estimated days for replenishment in case of backorder. |
| maxOrderQuantity | number | Maximum limit of pieces purchasable in a single order. |
| allowFreeShipping | boolean | The variant is eligible for free shipping according to general rules. |
| forceFreeShipping | boolean | If true, forces free shipping regardless of cart rules. |
Options
Options (e.g., "Size") are defined at the Product level, but it is at the Variant level that they come to life through the options map.
| Property | Type | Description |
|---|---|---|
| options | Object | Map of selected options: { "OPTION_ID": "OPTION_VALUE_ID" }. |
During the automatic generation of variants, the system intersects the options defined on the product and automatically assigns the corresponding tags to the variant, making it immediately filterable.
If you create a "Shoe Size" option with values 40, 41, 42… and associate it with the variant via automatic generation, the variant will already be tagged with all the sizes. By setting the Tag as filterable, customers will be able to filter by size in the frontend.
Pricing Strategy (Multi-Price & Multi-Currency)
A variant is not limited to a single price. Webround allows total flexibility via the prices array:
| Property | Type | Description |
|---|---|---|
| prices | Price[] | Array of prices applicable to this variant. |
| priceRanges | PriceRange[] | Price ranges (min/max) calculated on the variant's options. Used for rendering in product cards. |
Supported Pricing Models
- One-Time Price (
cadence: "once"): The classic sale. - Subscriptions: Prices with a frequency (
daily,monthly,yearly, etc.). The same variant can be sold as both a single purchase and a subscription.
It is not possible to define two prices with the same combination of
cadenceandcurrencyCode.
Comparative Price (Visual Discount)
The Compare Price is the original price shown crossed out next to the current price. It manages the perception of the discount directly in the product sheet.
Taxes: Net vs Gross
The technical advice is to always reason in terms of the Net price. The tax rate is determined by the Tax Zone (or Stripe Tax) based on the customer's location. Gross prices are only correct for the main market; for multinational sales, the net + tax zone calculation is the only way to ensure correct accounting.
Quantity Discounts (Tier Pricing)
Each price can include a quantityTable that automates volume-based discounting. The unit price is recalculated in real-time as the quantity in the cart changes.
Tags and Attributes
| Property | Type | Description |
|---|---|---|
| tags | Tag[] | Specific tags for the variant (e.g., Color, Size). |
| attributes | Attribute[] | Specific attributes for the variant. |
| assets | Asset[] | Specific multimedia resources for this variant. |
Marketing and Promotions
- Promotion Exclusion: It is possible to link specific promotions from which the variant must be excluded.
- Coupons: The variant can inherit the product's coupon rules or follow independent logic (controlled by
inheritDisableCoupons).
Complete Definition
interface Variant {
// Identity
id: string;
name: string;
slug: string;
isFavourite: boolean;
productId: string;
availability: "available" | "low_availability" | "not_available";
metadata: Record<string, unknown>;
// Inheritance
inheritAssets: boolean;
inheritAttributes: boolean;
inheritTagValues: boolean;
inheritShipping: boolean;
inheritTaxZones: boolean;
inheritCoupon: boolean;
// Operational / Warehouse
sku: string;
ean: string;
mpn: string;
quantity: number;
allowBackorder: boolean;
backorderDays: number;
maxOrderQuantity: number;
allowFreeShipping: boolean;
forceFreeShipping: boolean;
// Options
options: Record<string, string>; // { optionId: optionValueId }
// Prices
prices: Price[];
priceRanges: PriceRange[];
// Relations
tags: Tag[];
attributes: Attribute[];
assets: Asset[];
}
Price
Represents a specific price for the variant.
| Property | Type | Description |
|---|---|---|
| id | string (UUID) | Unique identifier of the price. |
| amount | number | Nominal value of the price. |
| netAmount | number | Unit net price. |
| grossAmount | number | Unit gross price (including tax). |
| netCompare | number | Net compare price (original price). |
| grossCompare | number | Gross compare price (original price including tax). |
| currencyCode | string | ISO currency code (e.g., EUR). |
| cadence | string | Payment frequency (e.g., once). |
| isDefault | boolean | Indicates if it is the main price for the current currency. |
| externalId | string | Stripe product ID or external system ID. |
| quantityTable | QuantityTable | null |
PriceRange
Describes the price range calculated based on the variant's options. Primarily used for rendering in product cards.
| Property | Type | Description |
|---|---|---|
| currencyCode | string | ISO currency code (e.g., EUR). |
| cadence | string | Payment frequency (e.g., once). |
| netMin | number | Minimum net price. |
| netMax | number | Maximum net price. |
| grossMin | number | Minimum gross price (VAT included). |
| grossMax | number | Maximum gross price. |
| compareNetMin | number | Minimum net compare price. |
| compareNetMax | number | Maximum net compare price. |
| compareGrossMin | number | Minimum gross compare price. |
| compareGrossMax | number | Maximum gross compare price. |
| rate | number | Applied VAT rate (e.g., 22). |
To show a "Promo" badge or a crossed-out price, compare grossMin with compareGrossMin. If compareGrossMin > grossMin, the variant is on sale.
QuantityTable (Tier Pricing)
| Property | Type | Description |
|---|---|---|
| min | number | Minimum quantity to activate the tier. |
| max | number | null |
| discountType | string | Discount type: percentage or fixed. |
| discountValue | number | Discount value. |
| rounding | string | null |
The final price is calculated by applying the corresponding tier discount to the amount (or grossAmount) value of the variant. If the quantity in the cart changes, the unit price is recalculated in real-time.
In product cards, use priceRanges to display the price and assets for the correct image based on the selected variant. The correct variant is identified by crossing the user's selections (options) with the product's variants.