stock_reference/created

Overview

Property	Value
Webhook type	stock_reference/created
Kafka topic	stock-reference.created
Direction	Platform → Your endpoint

Description

Fired when a new stock reference is created in the system. A stock reference links a product variant to a warehouse location and tracks its inventory quantities.

Trigger Conditions

• A product variant is assigned to a warehouse location for the first time
• A stock reference is created programmatically via the API
• The stock reference initially has status: DRAFT until validated

Message Envelope

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

The body field contains the full stock reference object as described below.

Body — Property Table

StockReference Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique stock reference identifier
organizationId	string (uuid)	No	Organization that owns this stock reference
locationId	string (uuid)	Yes	Warehouse location where the stock is held
productVariantId	string (uuid)	No	Associated product variant
reference	string	No	Internal reference code for this stock item
sku	string	No	Stock keeping unit identifier
status	enum	No	Stock reference status: DRAFT, VALID, ON_HOLD, INVALID
model	enum	No	Product model type: PRODUCT or BUNDLE
physicalQuantity	integer	No	Total physical quantity in stock
usableQuantity	integer	No	Quantity available for fulfillment
reservedQuantity	integer	No	Quantity reserved for pending orders (default 0)
criticalThreshold	integer	No	Alert threshold — triggers a critical-stock event when usable quantity falls below this value
lastSnapshotAt	string (ISO 8601)	Yes	Timestamp of the last inventory snapshot
lastSnapshotValue	integer	Yes	Quantity recorded at the last snapshot
height	float	Yes	Product height
width	float	Yes	Product width
length	float	Yes	Product length
distanceUnit	enum	Yes	Unit for dimensions: CM, IN, etc.
weight	float	Yes	Product weight
weightUnit	enum	Yes	Unit for weight: KG, LB, etc.
volume	float	Yes	Product volume
volumeUnit	enum	Yes	Unit for volume
alcoholRate	float	Yes	Alcohol percentage (for alcohol products)
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
storageProfile	StorageProfile	Yes	Storage profile associated with this stock reference
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": "stock_reference/created",
    "date": "2024-03-15T10:23:45.000Z"
  },
  "body": {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "locationId": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "productVariantId": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "reference": "REF-TSHIRT-WHITE-M",
    "sku": "TSHIRT-WHITE-M",
    "status": "DRAFT",
    "model": "PRODUCT",
    "physicalQuantity": 0,
    "usableQuantity": 0,
    "reservedQuantity": 0,
    "criticalThreshold": 5,
    "lastSnapshotAt": null,
    "lastSnapshotValue": null,
    "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",
    "storageProfile": null,
    "createdAt": "2024-03-15T10:23:45.000Z",
    "updatedAt": "2024-03-15T10:23:45.000Z"
  }
}

Related Events

• stock_reference/updated — fired when any stock reference field changes
• stock_reference/status_updated — fired when the status transitions (e.g. DRAFT → VALID)
• stock_reference/sku_updated — fired when the SKU is changed
• stock_reference/movement_created — fired when a stock movement is recorded

Notes

• usableQuantity is the key field for fulfillment logic — it equals physicalQuantity - reservedQuantity in most cases.
• A newly created stock reference always has status: DRAFT. It transitions to VALID after warehouse validation.
• The organizationId is read directly from data.organizationId (no nested accessor needed for this event).