Create Store category

What this endpoint does

Create the category that will group products in the Store. Use the returned category ID for readback.

INFO

Workflow

Create category → category ID → create product

Quick start

Use the environment selected by Try it. The example values are synthetic.

Authentication and permission

Send	Permission	Community scope
`Authorization: Bearer <apiKey>`	`store`	Community scope is derived from the key; do not send a community identifier.

Complete examples

{
  "name": "Agent Test Rewards",
  "displayOrder": 10
}

Success and readback

Branch on: meta.code = CATEGORY_CREATED

{
  "meta": {
    "status": "success",
    "statusCode": 201,
    "code": "CATEGORY_CREATED"
  },
  "message": "Create Store category successfully",
  "data": {
    "_id": "cat_agent_01",
    "name": "Agent Test Rewards",
    "displayOrder": 10
  }
}

CHECK

Readback

Read back with GET /categories/{categoryID}; the name, order, display settings, and limit policy must match.

Errors and recovery

Branch on meta.code, never message text.

HTTP	Machine code	What the caller should do	Retry?
400	`VALIDATION_FAILED`	Repair the field-keyed `detail` map.	No, fix first
401	`AUTH_API_KEY_REQUIRED`	Add the Authorization header.	No, fix first
401	`AUTH_API_KEY_INVALID`	Replace or rotate the key.	No, fix first
401	`AUTH_API_KEY_VALIDATION_FAILED`	Authentication could not be completed.	Yes, with backoff
403	`AUTH_PERMISSION_REQUIRED`	Request the store permission; no resource data is returned.	No, fix first
409	`STORE_RESOURCE_CONFLICT`	Reuse the existing category or choose another name.	After reconciliation
502	`STORE_DEPENDENCY_UNAVAILABLE`	Retry after a short backoff; the Store dependency is unavailable.	Yes, with backoff
500	`INTERNAL_ERROR`	Retry with exponential backoff and the same request context, then escalate.	Yes, with backoff

Retry safety

WARNING

Exact retry

Create is not idempotent. After a timeout, list by exact name before deciding whether to retry.

Gotchas

Avoid this mistake

Next steps

Create Store product

Create a product in the returned category.

Effective response fields

defaultPurchaseStatusID is the effective status: a non-null stored category override wins; otherwise the active community new_purchase default is returned; it is null when neither exists.

categoryPermission[].permission exposes roles, tags, users, combination, and isSelectAll only. Internal permission identifiers are never returned.

curl --location 'https://sgtr-api.returning.ai/v1/categories' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "name": "Agent Test Rewards", "displayOrder": 10 }'

{ "meta": { "status": "success", "statusCode": 201, "code": "CATEGORY_CREATED" }, "message": "Create Store category successfully", "data": { "_id": "cat_agent_01", "name": "Agent Test Rewards", "displayOrder": 10, "defaultPurchaseStatusID": "650906d314a3e564c56f3450", "categoryPermission": [ { "isEnabled": true, "type": "user", "permission": { "roles": [ "VIP Member" ], "tags": [ "Early Access" ], "users": [ "alex" ], "combination": [ { "type": "role", "values": [ "VIP Member" ] } ], "isSelectAll": false } } ] } }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Effective response fields#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Effective response fields