Reorder Categories (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/storefront/categories/reorder

Actual backend path: /v1/workspace/:workspaceId/storefront/categories/reorder

Description

Reorder storefront categories within the same parent group. This affects the order shown in the public storefront.

Personas: Workspace Owner (root), Staff with store.manage permission.

Authentication

Required: JWT token in Authorization header with store.manage permission.

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token: Bearer <token>
Content-Type	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

None.

Request Body

{
  "parentId": null,
  "orderedCategoryIds": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ]
}

Fields

Field	Type	Required	Description
parentId	string | null	No	Parent category ID. Use null or omit for top-level categories.
orderedCategoryIds	string[]	Yes	Ordered list of category IDs within the same parent.

Response 200 OK

{
  "categories": [
    {
      "id": "507f1f77bcf86cd799439011",
      "parentId": null,
      "name": "Electronics",
      "slug": "electronics",
      "description": "Electronic products",
      "imageUrl": "https://example.com/category.jpg",
      "sortOrder": 0,
      "status": "active"
    }
  ]
}

Common Errors

• 400 Bad Request: Invalid payload or missing fields
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Insufficient permissions (requires store.manage)
• 404 Not Found: Workspace or parent category not found
• 422 Unprocessable Entity: Validation error (invalid IDs or wrong parent)
• 500 Internal Server Error: Server error