variant/created

Overview

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

Description

Fired when a new product variant is created. A variant represents a specific SKU under a product — for example, a t-shirt in size M.

Trigger Conditions

• A variant is created via the GraphQL API
• A product import creates variants automatically
• model will be PRODUCT for standard variants or BUNDLE for bundle variants

Message Envelope

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

The body field contains the full 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 (unique per organization)
sku	string	No	Stock keeping unit (unique per organization)
barcode	string	Yes	EAN/UPC barcode
model	enum	No	PRODUCT or BUNDLE
status	enum	Yes	DRAFT, ACTIVE, ARCHIVED, DISABLED, HOLD
sourceType	enum	No	Origin source: CMS or APP
sourceId	string (uuid)	Yes	External source identifier
position	integer	Yes	Display sort order within the product
virtualProduct	boolean	No	Whether this is a virtual (non-physical) product
price	float	Yes	Variant price (overrides product 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: CM, IN, etc.
weight	float	Yes	Weight
weightUnit	enum	Yes	Unit for weight: KG, LB, etc.
volume	float	Yes	Volume
volumeUnit	enum	Yes	Unit for volume
alcoholRate	float	Yes	Alcohol percentage
originCountry	string	Yes	ISO 3166-1 alpha-2 country of origin
hsCode	string	Yes	Harmonized System customs code
customsValue	string	Yes	Declared customs value
customsDescription	string	Yes	Customs description text
publishedAt	string (ISO 8601)	Yes	Timestamp when the variant was 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/created",
    "date": "2024-03-15T10:23:45.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",
    "description": null,
    "reference": "REF-TSHIRT-WHITE-M",
    "sku": "TSHIRT-WHITE-M",
    "barcode": "3760000000001",
    "model": "PRODUCT",
    "status": "DRAFT",
    "sourceType": "CMS",
    "sourceId": null,
    "position": 1,
    "virtualProduct": false,
    "price": 25.00,
    "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": "Cotton T-shirt",
    "publishedAt": null,
    "createdAt": "2024-03-15T10:23:45.000Z",
    "updatedAt": "2024-03-15T10:23:45.000Z"
  }
}

Related Events

• variant/updated — fired when any variant field changes
• variant/status_updated — fired when the variant status transitions
• product/created — fired when the parent product is created

Notes

• The organizationId is read directly from data.organizationId.
• sku and reference are unique per organization and are the primary keys used in order lines and stock references.
• A newly created variant always has status: DRAFT until explicitly published.