Create store category

Creates a store category for the API-key's community and returns the created category.

Use this when a partner integration needs to add a storefront category or navigation section before attaching products to it.

Authentication:

Bearer API key in Authorization header

API key must have the store permission

Community is resolved from the API key token — do not pass communityID

Returns 401 if the key is missing, invalid, or expired

Returns 403 if the key does not include the store permission

Side effects:

A category is created for the resolved community

Publishes create:category

Downstream store service processes the write

Rate limits:

Standard API rate limits apply

Constraints:

name is required

defaultPurchaseStatusID, when provided, must be a valid ID accepted by the store service

categoryPermission entries must match the source store permission shape

Upstream store-service failures return 502

Example — create:

{
  "name": "Premium Rewards",
  "coverImage": "https://example.com/category.png",
  "shouldShowCover": true,
  "isArchived": false
}

Related endpoints:

GET /categories — list store categories

GET /categories/{categoryID} — read a single store category

PUT /categories/{categoryID} — update a store category

DELETE /categories/{categoryID} — delete a store category

{ "meta": { "status": "success", "statusCode": 201 }, "message": "Create category success.", "data": { "_id": "507f1f77bcf86cd799439021", "communityID": "6502c9e514a3e564c5c09c0a", "name": "Premium Rewards", "coverImage": "https://example.com/category.png", "shouldShowCover": true, "isArchived": false, "viewType": "full", "displayOrder": 0, "defaultPurchaseStatusID": "650906d314a3e564c56f3450", "createdAt": "2026-04-28T00:00:00.000Z", "updatedAt": "2026-04-28T00:00:00.000Z" } }

Request

Responses