Add Product Stock Movement (v1)

Method & Path

POST /api/v1/{workspaceId}/storefront/products/{productId}/stock-movements

Description

Adds a manual stock movement to a product inventory and increases the current stock.

Authentication

Required: Workspace auth with store.products.manage permission.

Headers

• Authorization: Bearer <token>
• Content-Type: application/json
• X-Staff-Id: <staffId> (when acting as staff)

Path Parameters

Name	Type	Required	Description
workspaceId	string	نعم	Workspace identifier
productId	string	نعم	Storefront product identifier

Request Body

{
  "quantity": 10,
  "direction": "in",
  "occurredAt": "2025-01-22T08:00:00.000Z",
  "note": "توريد جديد",
  "source": "goods-receipt"
}

Field	Type	Required	Description
quantity	number	نعم	Quantity to move (0.01–9999)
direction	string	لا	in (default) or out
occurredAt	string (ISO)	لا	When the movement occurred
note	string | null	لا	Optional note (max 1000)
source	"goods-receipt"	لا	When set with stock in, the movement is stored as goods-receipt (ادخال بضاعة) instead of manual-add. Invalid with direction: out.

Direction Values

• in: add to stock
• out: deduct from stock

Response 201 Created

{
  "movement": {
    "id": "66b3c1f52a6e9d2c52f7b123",
    "productId": "66b3c0e22a6e9d2c52f7b0aa",
    "orderId": null,
    "orderPublicId": null,
    "type": "goods-receipt",
    "quantity": 10,
    "direction": "in",
    "stockAfter": 55,
    "note": "توريد جديد",
    "actor": {
      "type": "staff",
      "id": "staff_123",
      "name": "Ahmed",
      "email": "ahmed@example.com"
    },
    "occurredAt": "2025-01-22T08:00:00.000Z",
    "createdAt": "2025-01-22T08:00:01.000Z"
  },
  "stockQuantity": 55
}

Common Errors

• 400 Bad Request: Invalid identifiers; or source: goods-receipt with direction: out.
• 401 Unauthorized: Missing/invalid token.
• 403 Forbidden: Missing store.products.manage permission.
• 404 Not Found: Product or workspace not found.
• 422 Unprocessable Entity: Invalid quantity or payload.
• 500 Internal Server Error: Unexpected error.