variant/updated

Overview

Property	Value
Webhook type	variant/updated
Kafka topic	variant.updated
Direction	Platform → Your endpoint

Description

Fired when any field on an existing variant is updated. This includes changes to dimensions, pricing, customs data, and catalog metadata.

Trigger Conditions

• A variant's title, description, or barcode is edited
• Pricing (price, vatRate, currency) is changed
• Physical dimensions or weight are updated
• Customs / shipping data (hsCode, originCountry, etc.) is modified
• The variant position within its product is changed

Message Envelope

{
  "header": {
    "organizationId": "org_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "messageId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "webhookId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type": "variant/updated",
    "date": "2024-03-15T10:23:45.000Z"
  },
  "body": { ... }
}

The body field contains the full updated variant object.

Body — Property Table

Variant Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique variant identifier
organizationId	string (uuid)	No	Organization that owns this variant
productId	string (uuid)	No	Parent product identifier
title	string	Yes	Variant display name
description	string	Yes	Variant description
reference	string	No	Internal reference code
sku	string	No	Stock keeping unit
barcode	string	Yes	EAN/UPC barcode
model	enum	No	PRODUCT or BUNDLE
status	enum	Yes	DRAFT, ACTIVE, ARCHIVED, DISABLED, HOLD
sourceType	enum	No	CMS or APP
sourceId	string (uuid)	Yes	External source identifier
position	integer	Yes	Display sort order
virtualProduct	boolean	No	Virtual product flag
price	float	Yes	Variant price
vatRate	float	Yes	VAT rate as decimal
currency	string	Yes	ISO 4217 currency code
height	float	Yes	Height
width	float	Yes	Width
length	float	Yes	Length
distanceUnit	enum	Yes	Unit for dimensions
weight	float	Yes	Weight
weightUnit	enum	Yes	Unit for weight
volume	float	Yes	Volume
volumeUnit	enum	Yes	Unit for volume
alcoholRate	float	Yes	Alcohol percentage
originCountry	string	Yes	Country of origin (ISO 3166-1 alpha-2)
hsCode	string	Yes	Harmonized System customs code
customsValue	string	Yes	Declared customs value
customsDescription	string	Yes	Customs description
publishedAt	string (ISO 8601)	Yes	Timestamp when published
createdAt	string (ISO 8601)	No	Creation timestamp
updatedAt	string (ISO 8601)	No	Last update timestamp

Full JSON Payload Sample

{
  "header": {
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "messageId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "webhookId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "type": "variant/updated",
    "date": "2024-03-15T14:45:00.000Z"
  },
  "body": {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "productId": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "title": "Classic White T-Shirt — Size M (Organic)",
    "description": "Made from 100% organic cotton.",
    "reference": "REF-TSHIRT-WHITE-M",
    "sku": "TSHIRT-WHITE-M",
    "barcode": "3760000000001",
    "model": "PRODUCT",
    "status": "ACTIVE",
    "sourceType": "CMS",
    "sourceId": null,
    "position": 1,
    "virtualProduct": false,
    "price": 27.50,
    "vatRate": 0.20,
    "currency": "EUR",
    "height": 2.0,
    "width": 20.0,
    "length": 30.0,
    "distanceUnit": "CM",
    "weight": 0.25,
    "weightUnit": "KG",
    "volume": null,
    "volumeUnit": null,
    "alcoholRate": null,
    "originCountry": "FR",
    "hsCode": "6109100010",
    "customsValue": "12.00",
    "customsDescription": "Organic cotton T-shirt",
    "publishedAt": "2024-03-12T08:00:00.000Z",
    "createdAt": "2024-03-15T10:23:45.000Z",
    "updatedAt": "2024-03-15T14:45:00.000Z"
  }
}

Related Events

• variant/created — fired when the variant is first created
• variant/status_updated — dedicated event for status transitions

Notes

• The organizationId is read directly from data.organizationId.
• The payload always contains the full current state — not just the changed fields.