List Product Stock Movements (v1)

Method & Path

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

Description

Returns recent stock movements for a product (manual additions and order-based adjustments).

Authentication

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

Headers

• Authorization: Bearer <token>
• X-Staff-Id: <staffId> (when acting as staff)

Path Parameters

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

Query Parameters

Name	Type	Required	Description
page	number	لا	Page number (default: 1)
limit	number	لا	Max results per page (1-100). Default: 10

Response 200 OK

{
  "movements": [
    {
      "id": "66b3c1f52a6e9d2c52f7b123",
      "productId": "66b3c0e22a6e9d2c52f7b0aa",
      "orderId": "66b3bfe92a6e9d2c52f7a0ff",
      "orderPublicId": "QFTPPWEZ",
      "type": "order-confirmed",
      "quantity": 4,
      "direction": "out",
      "stockAfter": 41,
      "note": "Order #QFTPPWEZ",
      "actor": {
        "type": "staff",
        "id": "staff_123",
        "name": "Ahmed",
        "email": "ahmed@example.com"
      },
      "occurredAt": "2025-01-22T09:00:00.000Z",
      "createdAt": "2025-01-22T09:00:01.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 23,
    "totalPages": 3
  }
}

Common Errors

• 400 Bad Request: Invalid identifiers.
• 401 Unauthorized: Missing/invalid token.
• 403 Forbidden: Missing store.products.manage permission.
• 404 Not Found: Product or workspace not found.
• 500 Internal Server Error: Unexpected error.