stock_reference/fulfillment_event

Overview

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

Description

Fired when a fulfillment lifecycle event occurs on a stock reference. These events track the integration status between the platform and external warehouse management systems (WMS), as well as critical stock alerts.

Trigger Conditions

• A fulfillment request for a stock reference is accepted by the WMS
• A fulfillment request is rejected by the WMS
• A stock reference is successfully integrated into the WMS (INTEGRATED)
• An integration error occurs (INTEGRATION_ERROR)
• A stock reference is removed from WMS integration
• The usable quantity falls below the criticalThreshold (CRITICAL_STOCK_LEVEL)
• A stock reference is waiting for restocking (AWAITING_STOCK)

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

The body field contains the fulfillment event with the parent stock reference nested.

Note on organizationId resolution: This event uses an organizationIdAccessor pattern — the organizationId is read from data.stockReference.organizationId.

Body — Property Table

FulfillmentEvent Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique fulfillment event identifier
stockReferenceId	string (uuid)	No	Parent stock reference ID
stockReference	StockReference	No	The parent stock reference object (see below)
type	enum	No	Event type: FULFILLMENT_ACCEPTED, FULFILLMENT_REJECTED, INTEGRATED, INTEGRATION_ERROR, REMOVED, CRITICAL_STOCK_LEVEL, AWAITING_STOCK
level	enum	No	Severity level: NORMAL, WARNING, ERROR
message	string	Yes	Optional human-readable message describing the event
date	string (ISO 8601)	No	Timestamp when the event occurred

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	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
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/fulfillment_event",
    "date": "2024-03-15T10:23:45.000Z"
  },
  "body": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "stockReferenceId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "stockReference": {
      "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": 3,
      "usableQuantity": 3,
      "reservedQuantity": 0,
      "criticalThreshold": 5,
      "lastSnapshotAt": "2024-03-15T08:00:00.000Z",
      "lastSnapshotValue": 10,
      "createdAt": "2024-03-10T09:00:00.000Z",
      "updatedAt": "2024-03-15T10:23:45.000Z"
    },
    "type": "CRITICAL_STOCK_LEVEL",
    "level": "WARNING",
    "message": "Usable quantity (3) is below critical threshold (5)",
    "date": "2024-03-15T10:23:45.000Z"
  }
}

Related Events

• stock_reference/updated — fired when stock quantities change
• stock_reference/movement_created — the movement that may have triggered a critical-level event
• stock_reference/status_updated — fired when stock reference status transitions

Notes

• This event uses organizationIdAccessor: (data) => data.stockReference.organizationId.
• CRITICAL_STOCK_LEVEL events fire automatically when usableQuantity drops below criticalThreshold after a movement.
• level: ERROR events (e.g., INTEGRATION_ERROR) indicate that operator intervention may be required.
• FULFILLMENT_ACCEPTED and FULFILLMENT_REJECTED reflect WMS acknowledgments for outbound shipment requests.