Create store category

Creates one store category for the API-key community and returns the created public category.

Use this when a partner integration needs to create a new storefront category or category shelf.

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, expired, or lacks access

Side effects:

Creates one category in the store service

Publishes the store category create event

Duplicate category names in the same community return 409

Rate limits:

Standard API rate limits apply

Constraints:

name is required and must be non-empty

viewType is optional and must be full or preview; the default is full

displayOrder is optional and must be an integer greater than or equal to 0

Use roleNames, tagNames, usernames, and defaultPurchaseStatusName in partner-facing requests

Do not send communityID; it is resolved from the API key

Public responses expose roles, tags, and users as string arrays only; backend-internal IDs are not returned

Public responses expose permission combinations through combination[].values

defaultPurchaseStatus is returned as a status name string or null, never as an object

i18n controls category name translations and defaults to disabled with an empty translation list

Example - create:

// Creates a category using readable role, tag, user, and purchase-status names.
{
  "name": "Premium Rewards",
  "coverImage": "https://example.com/category.png",
  "shouldShowCover": true,
  "isArchived": false,
  "viewType": "full",
  "displayOrder": 0,
  "categoryPermission": [
    {
      "type": "role",
      "permission": {
        "roleNames": [
          "VIP Member"
        ],
        "tagNames": [
          "Early Access"
        ],
        "usernames": [
          "alex"
        ],
        "combination": [],
        "isSelectAll": false
      },
      "purchaseLimit": {
        "isEnabled": true,
        "quantity": 1,
        "intervalCount": 1,
        "intervalUnit": "months"
      },
      "accessLevel": "full-access",
      "isEnabled": true
    }
  ],
  "defaultPurchaseStatusName": "Pending",
  "i18n": {
    "isTranslationEnabled": false,
    "nameTranslations": []
  }
}

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

curl --location 'https://adss-integration.returning.ai/apis/categories' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "name": "Premium Rewards", "coverImage": "https://example.com/category.png", "shouldShowCover": true, "isArchived": false, "viewType": "full", "displayOrder": 0, "categoryPermission": [ { "type": "role", "permission": { "roleNames": [ "VIP Member" ], "tagNames": [ "Early Access" ], "usernames": [ "alex" ], "combination": [], "isSelectAll": false }, "purchaseLimit": { "isEnabled": true, "quantity": 1, "intervalCount": 1, "intervalUnit": "months" }, "accessLevel": "full-access", "isEnabled": true } ], "defaultPurchaseStatusName": "Pending", "i18n": { "isTranslationEnabled": false, "nameTranslations": [] } }'

{ "meta": { "status": "success", "statusCode": 201 }, "message": "Create category success.", "data": { "_id": "67bc22b591b5284096627c6c", "communityID": "6502c97314a3e564c5bbfa84", "name": "Premium Rewards", "coverImage": "https://example.com/category.png", "shouldShowCover": true, "isArchived": false, "viewType": "full", "displayOrder": 0, "categoryPermission": [ { "type": "role", "permission": { "roles": [ "VIP Member" ], "tags": [ "Early Access" ], "users": [ "alex" ], "combination": [], "isSelectAll": false }, "purchaseLimit": { "isEnabled": true, "quantity": 1, "intervalCount": 1, "intervalUnit": "months" }, "accessLevel": "full-access", "isEnabled": true } ], "defaultPurchaseStatus": "Pending", "i18n": { "isTranslationEnabled": false, "nameTranslations": [] }, "createdAt": "2025-02-24T07:41:41.053Z", "updatedAt": "2026-05-25T05:15:38.547Z" } }

Request

Responses