Create Product Option (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/storefront/product-options

Actual backend path: /v1/workspace/:workspaceId/storefront/product-options

Description

Create a new store-level product option. Options can later be linked to products in product option groups.

Authentication

Required: JWT token in Authorization header.

Required Permissions: store.products.manage

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

Request Body

Field	Type	Required	Description
name	string	Yes	Option name (e.g. "كبير", "إضافي")
priceDelta	number	No	Price adjustment (default 0). Can be negative.
imageUrl	string | null	No	URL of option image (optional)
isAvailable	boolean	No	Whether option is available for selection in storefront (default true)
sortOrder	number	No	Display order (default 0)

Example

{
  "name": "كبير",
  "priceDelta": 2.5,
  "isAvailable": true,
  "sortOrder": 0
}

Response 201 Created

{
  "option": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439012",
    "storeId": "507f1f77bcf86cd799439013",
    "name": "كبير",
    "priceDelta": 2.5,
    "imageUrl": null,
    "isAvailable": true,
    "sortOrder": 0,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  }
}

Common Errors

• 400 Bad Request: Invalid request body
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Workspace or store not found
• 422 Unprocessable Entity: Validation failed (e.g. name required)
• 500 Internal Server Error: Server error