List Goods Receipt Stock Movements (v1)

Method & Path

GET /api/v1/{workspaceId}/storefront/stock-movements/goods-receipt

Description

Returns paginated stock movements recorded as goods receipt (type: goods-receipt), i.e. inventory added from the storefront admin «ادخال بضاعة» flow. Read-only listing for audit; there is no mutation endpoint for this list.

Authentication

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

Personas: Workspace Owner, Staff with store.products.manage. (Admin as applicable to workspace API.)

Headers

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

Path Parameters

Name	Type	Required	Description
workspaceId	string	نعم	Workspace identifier

Query Parameters

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

Response 200 OK

{
  "movements": [
    {
      "id": "66b3c1f52a6e9d2c52f7b123",
      "productId": "66b3c0e22a6e9d2c52f7b0aa",
      "orderId": null,
      "orderPublicId": null,
      "type": "goods-receipt",
      "quantity": 10,
      "direction": "in",
      "stockAfter": 55,
      "note": "توريد من المورد",
      "productName": "منتج تجريبي",
      "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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

Common Errors

• 401 Unauthorized: Missing/invalid token.
• 403 Forbidden: Missing store.products.manage permission.
• 404 Not Found: Store not found for workspace.
• 500 Internal Server Error: Unexpected error.