Create Storefront Domain (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/storefront/domain

Description

Create a new custom domain for a workspace storefront.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with store.manage permission.

Headers

Authorization: Bearer <workspace_token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Request Body

{
  "domain": "example.com"
}

Request Body Schema

Field	Type	Required	Description
domain	string	Yes	Domain name (min: 3, max: 253 characters)

Response 201 Created

{
  "domain": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439012",
    "domain": "example.com",
    "status": "pending",
    "verificationToken": null,
    "sslStatus": null,
    "createdAt": "2024-12-01T10:00:00.000Z",
    "updatedAt": "2024-12-01T10:00:00.000Z"
  }
}

Common Errors

400 Bad Request: Invalid domain format or domain already exists

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have store.manage permission

404 Not Found: Workspace not found

409 Conflict: Domain already configured for this or another workspace

500 Internal Server Error: Server error occurred while processing the request

Notes

• Domain name is normalized (lowercase, trimmed)
• Domain status starts as pending and requires verification
• Workspace subscription status is checked before processing the request