Introduction

This section defines the complete schemas for every event related to Product Variants on Webround Commerce. Variants allow for granular catalog management, enabling each combination of options (e.g., Size/Color) to have its own specific data or to inherit it from the parent product.

Why Listen to Variant Events

Integrating variant events allows you to manage the following in real-time:

SKU Synchronization: Manage distinct inventories and barcodes for every combination.
Specific Logistics: Define package weights and dimensions for variants that differ from the base product.
Data Inheritance: Monitor inheritance flags to understand which data is overridden (assets, tags, tax zones).
Marketplace Automation: Update child product listings on external platforms.

Complete Events and Payload Table

Below is the complete table with all links to the respective JSON examples:

Event	Payload Schema	JSON Example
`product-variant.created`	Variant Schema	Link
`product-variant.updated`	Variant Schema	Link
`product-variant.deleted`	Variant Deleted Schema	Link
`product-variant.assets.replaced`	Variant Assets Schema	Link
`product-variant.attributes.replaced`	Variant Attributes Schema	Link
`product-variant.tags.replaced`	Variant Tags Schema	Link
`product-variant.shipping-methods.replaced`	Variant Shipping Methods	Link
`product-variant.shipping-zones.replaced`	Variant Shipping Zones	Link
`product-variant.tax-zones.replaced`	Variant Tax Zones	Link

Variant Schema (`productVariantCreatedSchema`)

Field	Type	Notes
productId	`uuid`	Required. Parent product ID
variantId	`uuid`	Required. Unique variant ID
name	`string`	Required. Variant name
slug	`string`	Required. URL slug
visible	`boolean`	Required. Publication status
isFavourite	`boolean`	Required. Flag for featured variants
inheritAssets	`boolean`	Inherit assets from parent product
inheritTagValues	`boolean`	Inherit tags from parent product
inheritAttributes	`boolean`	Inherit technical attributes from parent product
inheritPackageDimensions	`boolean`	Inherit package dimensions from parent product
inheritShippingMethods	`boolean`	Inherit shipping methods from parent product
inheritShippingZones	`boolean`	Inherit shipping zones from parent product
inheritTaxZones	`boolean`	Inherit tax zones from parent product
inheritDisableCoupons	`boolean`	Inherit coupon restrictions from parent product
disableCoupons	`boolean`	Force disable coupons on this variant
packageWeight	`number - null`	Specific weight (grams)
packageLength	`number - null`	Specific length (mm)
packageWidth	`number - null`	Specific width (mm)
packageHeight	`number - null`	Specific height (mm)
createdAt	`isoDate`	Required
updatedAt	`isoDate`	Required
metadata	`any`	Custom metadata
translations	`any`	Localized translations

Variant Example

{
    "envelopeId": "6ded36ec-895c-4259-af34-1eda960a81c6",
    "eventType": "product-variant.created",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:30:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "name": "T-Shirt Webround - Blue - XL",
        "slug": "t-shirt-webround-blue-xl",
        "visible": true,
        "isFavourite": false,
        "inheritAssets": false,
        "inheritTagValues": true,
        "inheritAttributes": true,
        "inheritPackageDimensions": true,
        "inheritShippingMethods": true,
        "inheritShippingZones": true,
        "inheritTaxZones": true,
        "inheritDisableCoupons": true,
        "disableCoupons": false,
        "packageWeight": 300,
        "packageLength": null,
        "packageWidth": null,
        "packageHeight": null,
        "createdAt": "2026-02-22T22:30:00.000Z",
        "updatedAt": "2026-02-22T22:30:00.000Z",
        "metadata": null,
        "translations": {
            "en": { "name": "Webround T-Shirt - Blue - XL" }
        }
    },
    "eventId": "f4e3d2c1-b0a9-4131-8e9b-c5b7539f152a"
}

Variant Deleted Schema (`productVariantDeletedSchema`)

Field	Type	Notes
productId	`uuid`	Required
variantId	`uuid`	Required

Variant Deleted Example

{
    "envelopeId": "121bf365-57cf-45b2-a9ba-6e0b008d3bb8",
    "eventType": "product-variant.deleted",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:35:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3"
    },
    "eventId": "f2e1d0c9-b8a7-4a7b-b8c9-d0e1f2a3b4c5"
}

Variant Assets Schema (`productVariantAssetReplacedSchema`)

Field	Type	Notes
productId	`uuid`	Required
variantId	`uuid`	Required
assets	`object[]`	Required. Array of asset objects specific to the variant
assets[].id	`uuid`	Required
assets[].url	`string`	Required. Public URL of the asset
assets[].type	`string`	Required (e.g., `image/png`)
assets[].fileName	`string - null`	Original file name
assets[].size	`number - null`	Size in bytes
assets[].alt	`string - null`	Alternative text
assets[].thumbnail	`string - null`	Thumbnail URL
assets[].externalId	`string - null`	External storage reference

Variant Assets Example

{
    "envelopeId": "121bf365-57cf-45b2-a9ba-6e0b008d3bb8",
    "eventType": "product-variant.assets.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:40:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "assets": [
            {
                "id": "e87c6806-fa7f-442a-b002-ab2765d6ce6d",
                "url": "https://cdn.webround.com/assets/variant-blue.jpg",
                "type": "image/jpeg",
                "fileName": "blue.jpg",
                "size": 150000,
                "alt": "T-Shirt Blue View",
                "thumbnail": null,
                "externalId": null
            }
        ]
    },
    "eventId": "219c43f2-84c5-4889-9309-f2bd35f6b25d"
}

Variant Attributes Schema (`productVariantAttributeReplacedSchema`)

Field	Type	Notes
productId	`uuid`	Required
variantId	`uuid`	Required
attributes	`object[]`	Required. Technical attributes of the variant
attributes[].attributeId	`uuid`	Required. Attribute definition ID
attributes[].value	`string`	Required. Attribute value

Variant Attributes Example

{
    "envelopeId": "d6e7f8g9-h0i1-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-variant.attributes.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:45:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "attributes": [
            {
                "attributeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
                "value": "2000"
            }
        ]
    },
    "eventId": "320d54f3-95d6-5990-0410-03ce46g7c36e"
}

Variant Tags Schema (`productVariantTagReplacedSchema`)

Field	Type	Notes
productId	`uuid`	Required
variantId	`uuid`	Required
tagValues	`object[]`	Required. Array of current tag values for the variant
tagValues[].id	`uuid`	Required. Unique tag value ID
tagValues[].tagId	`string`	Required. Tag category ID
tagValues[].storeId	`string`	Required
tagValues[].value	`string`	Required. Text value
tagValues[].alias	`string - null`	Slug for URLs or internal references
tagValues[].visible	`boolean`	Required. Frontend visibility

Variant Tags Example

{
    "envelopeId": "0aaefdc7-237b-4aa5-9747-ddfb3e328e7c",
    "eventType": "product-variant.tags.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:05:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "tagValues": [
            {
                "id": "fd273b45-4332-4b82-a142-347efb60f30d",
                "tagId": "3f1bb99f-eea1-4bf7-8dfd-710c86dea0b2",
                "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
                "value": "Limited Edition",
                "alias": "limited-edition",
                "visible": true,
                "createdAt": "2026-02-22T23:00:00.000Z",
                "updatedAt": "2026-02-22T23:00:00.000Z"
            }
        ]
    },
    "eventId": "e87c6806-fa7f-442a-b002-ab2765d6ce6d"
}

Variant Shipping Methods Schema (`productVariantShippingMethodsReplacedSchema`)

Field	Type	Notes
productId	`uuid`	Required
variantId	`uuid`	Required
shippingMethods	`object[]`	Required. Specific shipping methods
shippingMethods[].label	`string`	Method name
shippingMethods[].availableCountries	`string[]`	ISO country codes enabled
shippingMethods[].pricing	`any`	Pricing configuration
shippingMethods[].enabled	`boolean`	Required

Variant Shipping Methods Example

{
    "envelopeId": "0aaefdc7-237b-4aa5-9747-ddfb3e328e7c",
    "eventType": "product-variant.shipping-methods.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:50:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "shippingMethods": [
            {
                "id": "57bb3d09-0a9b-4f00-a3b5-7ccee22ed9b3",
                "label": "Variant Express Courier",
                "provider": "DHL",
                "availableCountries": ["IT"],
                "etaMin": 24,
                "etaMax": 48,
                "pricing": {},
                "enabled": true,
                "maxWeight": 5000,
                "maxVolume": null,
                "assetId": null
            }
        ]
    },
    "eventId": "fbb514c4-9266-4a84-9ae5-01b1e012bd04"
}

Variant Shipping Zones Schema (`productVariantShippingZonesReplacedSchema`)

Field	Type	Notes
productId	`uuid`	Required
variantId	`uuid`	Required
shippingZones	`object[]`	Required. Specific shipping zones
shippingZones[].countryCode	`string`	Required. ISO country code
shippingZones[].taxRate	`number`	Required. Tax rate for the zone

Variant Shipping Zones Example

{
    "envelopeId": "f8g9h0i1-j2k3-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-variant.shipping-zones.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:55:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "shippingZones": [
            {
                "id": "8e83373e-3ff7-48c7-bf32-ef0677835446",
                "label": "Mainland Italy",
                "countryCode": "IT",
                "surchargePricing": null,
                "taxRate": 22,
                "stripeTaxRateId": "txr_123"
            }
        ]
    },
    "eventId": "1a6a5220-4964-4708-9c99-1c1860448676"
}

Variant Tax Zones Schema (`productVariantTaxZonesReplacedSchema`)

Field	Type	Notes
productId	`uuid`	Required
variantId	`uuid`	Required
taxZones	`object[]`	Required. Specific tax configuration
taxZones[].rate	`number`	Required. Tax percentage
taxZones[].isDefault	`boolean`	Required

Variant Tax Zones Example

{
    "envelopeId": "33ec26e5-f8bd-40fa-ac1d-c5a3a207a330",
    "eventType": "product-variant.tax-zones.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T22:58:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "taxZones": [
            {
                "id": "af3e7355-d663-4a6b-a295-decd8d87dbdc",
                "label": "Reduced VAT Variant",
                "rate": 10,
                "stripeId": "txr_456",
                "countryCode": "IT",
                "isDefault": false
            }
        ]
    },
    "eventId": "1a6a5220-4964-4708-9c99-1c1860448676"
}

Why Listen to Variant Events

Complete Events and Payload Table

Variant Schema (productVariantCreatedSchema)​

Variant Example​

Variant Deleted Schema (productVariantDeletedSchema)​

Variant Deleted Example​

Variant Assets Schema (productVariantAssetReplacedSchema)​

Variant Assets Example​

Variant Attributes Schema (productVariantAttributeReplacedSchema)​

Variant Attributes Example​

Variant Tags Schema (productVariantTagReplacedSchema)​

Variant Tags Example​

Variant Shipping Methods Schema (productVariantShippingMethodsReplacedSchema)​

Variant Shipping Methods Example​

Variant Shipping Zones Schema (productVariantShippingZonesReplacedSchema)​

Variant Shipping Zones Example​

Variant Tax Zones Schema (productVariantTaxZonesReplacedSchema)​

Variant Tax Zones Example​