stock_reference/movement_updated

Overview

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

Description

Fired when a stock movement is updated — typically when its status changes from PENDING to CONFIRMED or CANCELED.

Trigger Conditions

• A pending stock movement is confirmed after warehouse processing
• A pending stock movement is canceled before execution

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

The body field contains the updated movement 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

Root Object

Field	Type	Nullable	Description
stockReference	StockReference	No	The parent stock reference (see StockReference table)
movement	StockMovement	No	The updated movement (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
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

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
nature	enum	No	ORDER, RETURN, RECEPTION, WAREHOUSE_INVENTORY, SHOP_INVENTORY
type	enum	No	INCREMENT or DECREMENT
quantityType	enum	No	RESERVED, AVAILABLE, or PHYSICAL
status	enum	No	PENDING, CONFIRMED, or CANCELED
objectType	enum	Yes	DELIVERY_ORDER, RECEPTION, or RESERVATION
objectId	string	Yes	ID of the source object
message	string	Yes	Free-text comment
meta	object	Yes	Arbitrary metadata (JSON)
source	string	Yes	Source identifier
batchNumber	string	Yes	Batch or lot number
limitUsageDate	string (ISO 8601)	Yes	Expiry / best-before date

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_updated",
    "date": "2024-03-15T11:05:00.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-15T11:05:00.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_created — fired when a new movement is recorded
• stock_reference/updated — fired when the parent stock reference quantities change

Notes

• This event uses organizationIdAccessor: (data) => data.stockReference.organizationId.
• The status field on the movement is the key changed field in this event (e.g., PENDING → CONFIRMED).