List Store categories

What this endpoint does

Find category IDs and display order before reading a category or creating products.

INFO

Workflow

List categories → category ID → products

NOTE

List behavior

Empty results keep the same collection shape with empty arrays and zero totals. Use the documented pagination fields for later pages.

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

No JSON body is sent. Replace each {pathParameter} and use the query parameters documented below.

Success and readback

Branch on: meta.code = CATEGORIES_RETRIEVED

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "CATEGORIES_RETRIEVED",
    "skip": 0,
    "limit": 20,
    "total": 1
  },
  "message": "List Store categories successfully",
  "data": [
    {
      "_id": "cat_agent_01",
      "name": "Agent Test Rewards",
      "displayOrder": 10
    }
  ]
}

CHECK

Readback

This collection response is the readback. An empty result returns data: [] with skip, limit, and total in meta.

Errors and recovery

Branch on meta.code, never message text.

HTTP	Machine code	What the caller should do	Retry?
400	`VALIDATION_FAILED`	Repair the named request field before retrying.	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
500	`INTERNAL_ERROR`	Retry with exponential backoff and the same request context, then escalate.	Yes, with backoff

Retry safety

TIP

Exact retry

This read is safe to retry with exponential backoff.

Gotchas

Avoid this mistake

Next steps

List Store products

Read one category or create a new one.

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.users contains resolved active CommunityMember usernames in configured order. Internal permission identifiers are not exposed; unresolved members are omitted from users.

A fields projection may omit these item properties.

curl --location 'https://sgtr-api.returning.ai/v1/categories?skip=0&limit=20&sort=displayOrder%3Aasc&fields=name%2CdisplayOrder&search=keyword%3Aagent&filter=isArchived%3Afalse&userID=usr_agent_01' \ --header 'Authorization: Bearer XXXXXX'

{ "meta": { "status": "success", "statusCode": 200, "code": "CATEGORIES_RETRIEVED", "skip": 0, "limit": 20, "total": 1 }, "message": "List Store categories successfully", "data": [ { "_id": "cat_agent_01", "displayOrder": 10, "name": "Agent Test Rewards", "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