stock_reference/status_updated

Overview

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

Description

Fired when the status of a stock reference changes. Stock reference status controls whether the item is available for fulfillment.

Trigger Conditions

• A stock reference is validated and transitions to VALID
• A stock reference is placed on hold (ON_HOLD) by an operator
• A stock reference is marked as INVALID due to a data or integration error
• A stock reference transitions back from ON_HOLD to VALID

Status Values

Status	Description
DRAFT	Newly created, not yet validated for fulfillment
VALID	Active and available for fulfillment
ON_HOLD	Temporarily suspended — not available for fulfillment
INVALID	Invalid state — requires operator action

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

The body field contains the full stock reference with the new status.

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
productVariantId	string (uuid)	No	Associated product variant
reference	string	No	Internal reference code
sku	string	No	Stock keeping unit
status	enum	No	Updated status: DRAFT, VALID, ON_HOLD, INVALID
model	enum	No	PRODUCT or BUNDLE
physicalQuantity	integer	No	Total physical quantity
usableQuantity	integer	No	Available quantity
reservedQuantity	integer	No	Reserved quantity
criticalThreshold	integer	No	Alert threshold
lastSnapshotAt	string (ISO 8601)	Yes	Timestamp of the last inventory snapshot
lastSnapshotValue	integer	Yes	Quantity at 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
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/status_updated",
    "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": "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",
    "createdAt": "2024-03-10T09:00:00.000Z",
    "updatedAt": "2024-03-15T10:23:45.000Z"
  }
}

Related Events

• stock_reference/updated — generic update event also fired on status changes
• stock_reference/fulfillment_event — fulfillment lifecycle events that may trigger status changes

Notes

• The organizationId is read directly from data.organizationId.
• Only VALID stock references are eligible for fulfillment order assignment.
• ON_HOLD status prevents new fulfillment requests but does not cancel existing ones.