stock_reference/movement_created

Overview

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

Description

Fired when a stock movement is confirmed on a stock reference. Stock movements record every change to inventory quantities — inbound receipts, outbound fulfillments, warehouse adjustments, and returns.

Trigger Conditions

• A delivery order fulfillment increments or decrements stock
• A goods reception (inbound) adds stock to a warehouse location
• A warehouse inventory adjustment is applied
• A return adds stock back to a location

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

The body field contains a movement object with the parent stock reference nested.

Note on organizationId resolution: This event uses an organizationIdAccessor pattern — the organizationId is read from data.stockReference.organizationId, not from the top-level payload. This means the webhook subscription is matched via the nested stockReference object.

Body — Property Table

Root Object

Field	Type	Nullable	Description
stockReference	StockReference	No	The parent stock reference (see StockReference table)
movement	StockMovement	No	The movement that was recorded (see StockMovement 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	DRAFT, VALID, ON_HOLD, INVALID
model	enum	No	PRODUCT or BUNDLE
physicalQuantity	integer	No	Total physical quantity after the movement
usableQuantity	integer	No	Available quantity after the movement
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

StockMovement Object

Field	Type	Nullable	Description
id	string (uuid)	No	Unique movement identifier
stockReferenceId	string (uuid)	No	Parent stock reference ID
date	string (ISO 8601)	No	Date when the movement occurred
quantity	integer	No	Requested movement quantity
executedQuantity	integer	No	Actually executed quantity (may differ from quantity in partial fulfillments)
nature	enum	No	Movement nature: ORDER, RETURN, RECEPTION, WAREHOUSE_INVENTORY, SHOP_INVENTORY
type	enum	No	Direction: INCREMENT (stock in) or DECREMENT (stock out)
quantityType	enum	No	Which quantity bucket was affected: RESERVED, AVAILABLE, PHYSICAL
status	enum	No	Movement status: PENDING, CONFIRMED, CANCELED
objectType	enum	Yes	Source object type: DELIVERY_ORDER, RECEPTION, RESERVATION
objectId	string	Yes	ID of the source object (e.g., delivery order ID)
message	string	Yes	Free-text comment on the movement
meta	object	Yes	Arbitrary metadata (JSON)
source	string	Yes	Source identifier (stored as source_id)
batchNumber	string	Yes	Batch or lot number for traceability
limitUsageDate	string (ISO 8601)	Yes	Expiry / best-before date for the batch

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/movement_created",
    "date": "2024-03-15T10:23:45.000Z"
  },
  "body": {
    "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": 148,
      "usableQuantity": 138,
      "reservedQuantity": 10,
      "criticalThreshold": 5,
      "lastSnapshotAt": "2024-03-15T08:00:00.000Z",
      "lastSnapshotValue": 150,
      "createdAt": "2024-03-10T09:00:00.000Z",
      "updatedAt": "2024-03-15T10:23:45.000Z"
    },
    "movement": {
      "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
      "stockReferenceId": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "date": "2024-03-15T10:23:45.000Z",
      "quantity": 2,
      "executedQuantity": 2,
      "nature": "ORDER",
      "type": "DECREMENT",
      "quantityType": "PHYSICAL",
      "status": "CONFIRMED",
      "objectType": "DELIVERY_ORDER",
      "objectId": "b8c9d0e1-f2a3-4567-bcde-678901234567",
      "message": null,
      "meta": null,
      "source": null,
      "batchNumber": null,
      "limitUsageDate": null
    }
  }
}

Related Events

• stock_reference/movement_updated — fired when the movement status changes
• stock_reference/updated — fired after the parent stock reference quantities are recalculated
• stock_reference/fulfillment_event — higher-level fulfillment lifecycle events

Notes

• This event uses organizationIdAccessor: (data) => data.stockReference.organizationId. Webhook subscriptions are matched using stockReference.organizationId, not a top-level organizationId field.
• executedQuantity may be less than quantity when only partial fulfillment was possible.
• The stockReference quantities in the payload reflect the state after the movement was applied.