Introduction

This section defines the complete schemas for every product-related event on Webround Commerce.

Why listen to Product Events

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

Catalog synchronization across external marketplaces (Amazon, eBay, etc.).
Automated updates for marketing feeds and social commerce.
Centralized management of multimedia assets on external CDNs.
Integration with Management Systems (ERP) for logistics and technical data sheets.

Complete Events and Payload Table

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

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

Product Schema (`productCreatedSchema`)

Field	Type	Notes
id	`uuid`	Required
name	`string`	Required
seoDescription	`string - null`	Description for search engines
htmlDescription	`string - null`	Sanitized description (HTML)
visible	`boolean`	Required (Publication status)
metadata	`object - null`	Product metadata
deliveryMethods	`string[]`	Required (e.g., `["shipping", "digital"]`)
packageWeight	`number - null`	Weight in grams (Integer)
packageLength	`number - null`	Length in mm (Integer)
packageWidth	`number - null`	Width in mm (Integer)
packageHeight	`number - null`	Height in mm (Integer)
defaultTaxRate	`number - null`	Default VAT rate (Integer)
defaultStripeTaxRateId	`string - null`	Stripe Tax Rate ID
disableCoupons	`boolean`	Required
createdAt	`isoDate`	Required
updatedAt	`isoDate`	Required
translations	`object - null`	Object containing localized translations

Product Example

{
    "envelopeId": "57bb3d09-0a9b-4f00-a3b5-7ccee22ed9b3",
    "eventType": "product.created",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:15:00.000Z",
    "data": {
        "id": "5a90f5ed-2785-44df-958b-841d0148a711",
        "name": "Official Webround T-Shirt",
        "seoDescription": "The official cotton t-shirt.",
        "htmlDescription": "<p>T-shirt <strong>100% cotton</strong>.</p>",
        "visible": true,
        "deliveryMethods": ["shipping"],
        "packageWeight": 250,
        "packageLength": 300,
        "packageWidth": 200,
        "packageHeight": 20,
        "defaultTaxRate": 22,
        "defaultStripeTaxRateId": "txr_...",
        "disableCoupons": false,
        "createdAt": "2026-02-22T21:15:00.000Z",
        "updatedAt": "2026-02-22T21:15:00.000Z",
        "translations": {
            "en": {
                "name": "Official Webround T-Shirt",
                "seoDescription": "The official organic cotton t-shirt."
            }
        }
    },
    "eventId": "54f3d2ac-7cf4-40ec-acef-38fffaf60c94"
}

Deleted Product Schema (`productDeletedSchema`)

Field	Type	Notes
id	`uuid`	Required (ID of the deleted product)

Deleted Product Example

{
    "envelopeId": "0b1c2d3e-4f5g-6h7i-8j9k-l0m1n2o3p4q5",
    "eventType": "product.deleted",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:20:00.000Z",
    "data": {
        "id": "a7b6c5d4-e3f2-1g0h-i9j8-k7l6m5n4o3p2"
    },
    "eventId": "f2e1d0c9-b8a7-4a7b-b8c9-d0e1f2a3b4c5"
}

Product Asset Schema (`productAssetReplacedSchema`)

This event is triggered when the entire collection of assets (images, videos, documents) for a product is updated or overwritten.

Field	Type	Notes
productId	`uuid v4`	Required
assets	`object[]`	Required. Array of asset objects
assets[].id	`uuid v4`	Required
assets[].url	`string`	Required. Public URL of the asset
assets[].type	`string`	Required (e.g., `image/jpeg`, `video/mp4`)
assets[].fileName	`string - null`	Original file name
assets[].size	`number - null`	Size in bytes
assets[].alt	`string - null`	Alternative text for accessibility
assets[].thumbnail	`string - null`	Thumbnail URL (if applicable)
assets[].externalId	`string - null`	Reference ID on external storage
assets[].createdAt	`isoDate`	Required
assets[].updatedAt	`isoDate`	Required

Product Asset Example

{
    "envelopeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product.assets.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:30:00.000Z",
    "data": {
        "productId": "a7b6c5d4-e3f2-41d4-a716-446655440000",
        "assets": [
            {
                "id": "e5f6g7h8-i9j0-4c3d-d4e5-f6g7h8i9j0k1",
                "url": "https://cdn.webround.com/assets/product-main.jpg",
                "type": "image/jpeg",
                "fileName": "tshirt-front.jpg",
                "size": 102400,
                "alt": "T-Shirt Front View",
                "thumbnail": null,
                "externalId": null,
                "createdAt": "2026-02-22T21:30:00.000Z",
                "updatedAt": "2026-02-22T21:30:00.000Z"
            }
        ]
    },
    "eventId": "f3e2d1c0-b9a8-4a7b-b8c9-d0e1f2a3b4c5"
}

Product Attributes Schema (`productAttributeReplacedSchema`)

This schema is used when the technical attributes of a product (e.g., material, collection, technical specifications) are updated in bulk.

Field	Type	Notes
productId	`uuid v4`	Required
attributes	`object[]`	Required. List of associated attributes
attributes[].attributeId	`uuid v4`	Required. Reference to attribute master data
attributes[].value	`string`	Required. Value assigned to the attribute

Product Attributes Example

{
    "envelopeId": "b8c9d0e1-f2a3-4b4c-5d6e-7f8g9h0i1j2k",
    "eventType": "product.attributes.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:40:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "attributes": [
            {
                "attributeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
                "value": "CODE_ABCDEF"
            },
            {
                "attributeId": "9f8e7d6c-5b4a-3f2e-1d0c-b9a8f7e6d5c4",
                "value": "2100"
            }
        ]
    },
    "eventId": "219c43f2-84c5-4889-9309-f2bd35f6b25d"
}

Product Tag Schema (`productTagReplacedSchema`)

This event is triggered when the entire set of tag values associated with a product is overwritten. Tags are used for categorization, filtering, and logical organization of the catalog.

Field	Type	Notes
productId	`uuid v4`	Required
tagValues	`object[]`	Required. Array of current tag values
tagValues[].id	`uuid v4`	Required. Unique ID of the tag value
tagValues[].tagId	`uuid v4`	Required. ID of the parent tag category
tagValues[].storeId	`uuid v4`	Required
tagValues[].value	`string`	Required. The textual value of the tag
tagValues[].alias	`string - null`	Slug/Alias for URLs or internal references
tagValues[].visible	`boolean`	Required. Frontend visibility
tagValues[].createdAt	`isoDate`	Required
tagValues[].updatedAt	`isoDate`	Required

Product Tag Example

{
    "envelopeId": "d1e2f3g4-h5i6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.tags.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:45:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "tagValues": [
            {
                "id": "e2f3g4h5-i6j7-k8l9-m0n1-o2p3q4r5s6t7",
                "tagId": "f3g4h5i6-j7k8-l9m0-n1o2-p3q4r5s6t7u8",
                "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
                "value": "New Collection",
                "alias": "new-collection",
                "visible": true,
                "createdAt": "2026-02-22T21:40:00.000Z",
                "updatedAt": "2026-02-22T21:40:00.000Z"
            }
        ]
    },
    "eventId": "f4e3d2c1-b0a9-4131-8e9b-c5b7539f152a"
}

Product Options Schema (`productOptionValuesReplacedSchema`)

Defines the sorting and association of product options (e.g., Size, Color) to their respective tag values.

Field	Type	Notes
productId	`uuid v4`	Required
options	`object[]`	Required. Option configuration array
options[].optionId	`uuid v4`	Required. ID of the option
options[].tagValueId	`uuid v4 - null`	Reference to the associated tag value
options[].position	`number`	Required. Positioning index

Product Options Example

{
    "envelopeId": "e1f2g3h4-i5j6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.option-values.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T21:50:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "options": [
            {
                "optionId": "b1b2b3b4-b5b6-4b7b-b8b9-b0b1b2b3b4b5",
                "tagValueId": "e2f3g4h5-i6j7-k8l9-m0n1-o2p3q4r5s6t7",
                "position": 0
            }
        ]
    },
    "eventId": "12345678-1234-4321-abcd-1234567890ab"
}

Product Shipping Methods Schema (`productShippingMethodsReplacedSchema`)

Field	Type	Notes
productId	`uuid v4`	Required
shippingMethods	`object[]`	Required. Enabled shipping methods
shippingMethods[].label	`string`	Name of the method
shippingMethods[].pricing	`any`	Pricing/rules configuration
shippingMethods[].enabled	`boolean`	Required

Product Shipping Methods Example

{
    "envelopeId": "f1g2h3i4-j5k6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.shipping-methods.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "shippingMethods": [
            {
                "id": "s1s2s3s4-s5s6-4s7s-s8s9-s0s1s2s3s4s5",
                "label": "Express Courier",
                "availableCountries": ["IT", "FR", "DE"],
                "enabled": true,
                "createdAt": "2026-02-22T21:55:00.000Z",
                "updatedAt": "2026-02-22T21:55:00.000Z"
            }
        ]
    },
    "eventId": "87654321-4321-1234-dcba-ba0987654321"
}

Product Shipping Zones Schema (`productShippingZonesReplacedSchema`)

Field	Type	Notes
productId	`uuid v4`	Required
shippingZones[].countryCode	`string`	Required. ISO country code
shippingZones[].taxRate	`number`	Required. Tax rate for the zone

Product Shipping Zones Example

{
    "envelopeId": "g1h2i3j4-k5l6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.shipping-zones.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "shippingZones": [
            {
                "id": "z1z2z3z4-z5z6-4z7z-z8z9-z0z1z2z3z4z5",
                "label": "Mainland Italy",
                "countryCode": "IT",
                "taxRate": 22,
                "createdAt": "2026-02-22T21:58:00.000Z",
                "updatedAt": "2026-02-22T21:58:00.000Z"
            }
        ]
    },
    "eventId": "abcdef12-3456-7890-abcd-ef1234567890"
}

Product Tax Zones Schema (`productTaxZonesReplacedSchema`)

Field	Type	Notes
productId	`uuid v4`	Required
taxZones[].rate	`number`	Required. Tax percentage
taxZones[].isDefault	`boolean`	Required

Product Tax Zones Example

{
    "envelopeId": "h1i2j3k4-l5m6-4a7b-b8c9-d0e1f2a3b4c5",
    "eventType": "product.tax-zones.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "taxZones": [
            {
                "id": "t1t2t3t4-t5t6-4t7t-t8t9-t0t1t2t3t4t5",
                "label": "Standard VAT",
                "rate": 22,
                "isDefault": true,
                "createdAt": "2026-02-22T22:00:00.000Z",
                "updatedAt": "2026-02-22T22:00:00.000Z"
            }
        ]
    },
    "eventId": "fdecba98-7654-3210-fedc-ba9876543210"
}

Why listen to Product Events

Complete Events and Payload Table

Product Schema (productCreatedSchema)​

Product Example​

Deleted Product Schema (productDeletedSchema)​

Deleted Product Example​

Product Asset Schema (productAssetReplacedSchema)​

Product Asset Example​

Product Attributes Schema (productAttributeReplacedSchema)​

Product Attributes Example​

Product Tag Schema (productTagReplacedSchema)​

Product Tag Example​

Product Options Schema (productOptionValuesReplacedSchema)​

Product Options Example​

Product Shipping Methods Schema (productShippingMethodsReplacedSchema)​

Product Shipping Methods Example​

Product Shipping Zones Schema (productShippingZonesReplacedSchema)​

Product Shipping Zones Example​

Product Tax Zones Schema (productTaxZonesReplacedSchema)​

Product Tax Zones Example​