Introduction

This section defines the complete schemas for every event related to SKUs (Stock Keeping Units) on Webround Commerce. The SKU represents the minimum sellable and traceable unit in the warehouse, uniquely linked to a product variant. This is where critical information regarding pricing, stock availability, and sales logic is managed.

Why Listen to SKU Events

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

• Multi-Warehouse Stock Synchronization: Immediate update of available quantities between Webround and your management systems (ERP/WMS).
• Price and Currency Management: Monitoring of price lists, comparison prices (sales), and different payment cadences.
• Sales Logic and Backorders: Automation of processes based on product availability, including backorder days and order quantity limits.
• Tax Integration (Stripe): Alignment of external tax codes for automatic tax calculation at checkout.

Complete Events and Payload Table

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

Event	Payload Schema	JSON Example
product-sku.created	SKU Schema	Link
product-sku.updated	SKU Schema	Link
product-sku.deleted	SKU Deleted Schema	Link
product-sku.stock.replaced	SKU Stock Schema	Link
product-sku.prices.replaced	SKU Prices Schema	Link

---

SKU Schema (productSkuCreatedSchema)

Field	Type	Notes
id	uuid	Required. Unique SKU ID
storeId	uuid	Required. Associated store ID
productId	uuid	Required. Parent product ID
variantId	uuid	Required. Linked variant ID
sku	string	Required. Identification code (Stock Keeping Unit)
isFavourite	boolean	Required. Favorite flag
externalId	string - null	Reference ID in external systems (e.g., ERP)
useStripeTax	boolean	Automatic tax calculation via Stripe Tax
taxCodeExternalId	string - null	External tax code (Stripe Tax Code)
purchaseRestock	boolean	Enable stock replenishment on purchase
allowBackorder	boolean	Allow purchase even if out of stock
allowFreeShipping	boolean	Enable free shipping eligibility
forceFreeShipping	boolean	Always force free shipping for this SKU
backorderDays	number	Estimated days for backorder replenishment
maxOrderQuantity	number	Maximum purchasable quantity per single order
createdAt	isoDate	Required
updatedAt	isoDate	Required

SKU Example

{
    "envelopeId": "a1b2c3d4-e5f6-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-sku.created",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:10:00.000Z",
    "data": {
        "id": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3",
        "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "sku": "WR-TSHIRT-BLU-XL",
        "isFavourite": true,
        "externalId": "SKU-9988-EXT",
        "useStripeTax": true,
        "taxCodeExternalId": "txcd_99999999",
        "purchaseRestock": true,
        "allowBackorder": false,
        "allowFreeShipping": true,
        "forceFreeShipping": false,
        "backorderDays": 0,
        "maxOrderQuantity": 10,
        "createdAt": "2026-02-22T23:10:00.000Z",
        "updatedAt": "2026-02-22T23:10:00.000Z"
    },
    "eventId": "e4f5g6h7-i8j9-4a5b-b6c7-d8e9f0a1b2c3"
}

---

SKU Deleted Schema (productSkuDeletedSchema)

Field	Type	Notes
productId	uuid	Required
variantId	uuid	Required
skuId	uuid	Required

SKU Deleted Example

{
    "envelopeId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-sku.deleted",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:15:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "skuId": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3"
    },
    "eventId": "f5g6h7i8-j9k0-4a5b-b6c7-d8e9f0a1b2c3"
}

---

SKU Stock Schema (productSkuStockReplacedSchema)

Field	Type	Notes
productId	uuid	Required
variantId	uuid	Required
skuId	uuid	Required
stock	object[]	Required. Array of stock levels per warehouse
stock[].warehouseId	uuid	Required. Warehouse ID
stock[].quantity	number	Required. Available integer quantity

SKU Stock Example

{
    "envelopeId": "c3d4e5f6-g7h8-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-sku.stock.replaced",
    "initiatedBy": "[email protected]",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:20:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "skuId": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3",
        "stock": [
            {
                "warehouseId": "w1z2x3c4-v5b6-4n7m-8a9s-d0f1g2h3j4k5",
                "quantity": 150
            },
            {
                "warehouseId": "w9z8x7c6-v5b4-4n3m-2a1s-d0f9g8h7j6k5",
                "quantity": 45
            }
        ]
    },
    "eventId": "g6h7i8j9-k0l1-4a5b-b6c7-d8e9f0a1b2c3"
}

---

SKU Prices Schema (productSkuPricesReplacedSchema)

Field	Type	Notes
productId	uuid	Required
variantId	uuid	Required
skuId	uuid	Required
prices	object[]	Required. List of applied price lists
prices[].currencyCode	string	Required. ISO currency code (e.g., "EUR")
prices[].cadence	string	Required. Payment frequency (e.g., "once", "month")
prices[].amount	string	Required. Price in decimal string format
prices[].comparePrice	string - null	Original price for discount display
prices[].externalId	string - null	External price system ID (e.g., Stripe Price ID)
prices[].isDefault	boolean	Required. Identifies the primary price
prices[].quantityTable	any - null	Table for quantity discounts (Tiered Pricing)

SKU Prices Example

{
    "envelopeId": "d4e5f6g7-h8i9-4a5b-b6c7-d8e9f0a1b2c3",
    "eventType": "product-sku.prices.replaced",
    "storeId": "7292a83e-967b-4861-80a5-2964e52003c4",
    "occurredAt": "2026-02-22T23:25:00.000Z",
    "data": {
        "productId": "5a90f5ed-2785-44df-958b-841d0148a711",
        "variantId": "b2c3d4e5-f6g7-4a5b-b6c7-d8e9f0a1b2c3",
        "skuId": "c1d2e3f4-g5h6-4a5b-b6c7-d8e9f0a1b2c3",
        "prices": [
            {
                "currencyCode": "EUR",
                "cadence": "once",
                "amount": "29.90",
                "comparePrice": "39.90",
                "externalId": "price_1Gs9X2L...",
                "isDefault": true,
                "quantityTable": null
            }
        ]
    },
    "eventId": "h7i8j9k0-l1m2-4a5b-b6c7-d8e9f0a1b2c3"
}