stock_reference/updated

Overview

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

Description

Fired when any field on an existing stock reference is modified. This includes changes to quantities, dimensional data, storage profiles, and other metadata. Quantity changes triggered by stock movements may also produce this event.

Trigger Conditions

• A warehouse operator updates stock reference fields (dimensions, thresholds, etc.)
• An inventory import updates quantity values on a stock reference
• The storage profile assignment changes

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/updated",
    "date": "2024-03-15T10:23:45.000Z"
  },
  "body": { ... }
}

The body field contains the full updated stock reference object.

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
criticalThreshold	integer	No	Alert threshold for low-stock warnings
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
weight	float	Yes	Product weight
weightUnit	enum	Yes	Unit for weight
volume	float	Yes	Product 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
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/updated",
    "date": "2024-03-15T14:35:22.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": "VALID",
    "model": "PRODUCT",
    "physicalQuantity": 150,
    "usableQuantity": 140,
    "reservedQuantity": 10,
    "criticalThreshold": 5,
    "lastSnapshotAt": "2024-03-15T08:00:00.000Z",
    "lastSnapshotValue": 145,
    "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-10T09:00:00.000Z",
    "updatedAt": "2024-03-15T14:35:22.000Z"
  }
}

Related Events

• stock_reference/created — fired when the stock reference is first created
• stock_reference/status_updated — dedicated event for status transitions
• stock_reference/sku_updated — dedicated event for SKU changes
• stock_reference/movement_created — fired when a stock movement occurs

Notes

• The payload always contains the full current state of the stock reference, not just the changed fields.
• usableQuantity reflects the real-time available stock after all reservations.
• The organizationId is read directly from data.organizationId.