List store categories - Returning.AI-dev

Returns a paginated list of store categories for the API-key's community, with optional sorting, field projection, search, filtering, and user visibility filtering.

Use this when a partner integration needs to render storefront navigation, category shelves, or category selectors before showing products.

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

Rate limits:

Standard API rate limits apply

Constraints:

skip defaults to 0 and must be at least 0

limit defaults to 20 and is capped at 100

fields is a comma-separated projection; projected responses include only requested public fields

Readable defaultPurchaseStatus is returned as a status name string when available; the backend-internal status ID is not exposed

Permission responses expose readable role names, tag names, usernames, and readable combination values only; backend-internal IDs are not exposed

permission.combination[].values contains resolved role or tag names, for example { "type": "role", "values": ["all", "Professional", "Master"] }; combination IDs are backend-internal and are not returned

Invalid query syntax or unsupported fields return 400

Upstream store-service failures return 502

Example - list:

// Lists active categories with readable public fields.
{ "query": "?skip=0&limit=20&sort=displayOrder:asc&fields=name,displayOrder,defaultPurchaseStatus&search=keyword:premium&filter=isArchived:false" }

Related endpoints:

GET /stores - read store configuration

POST /categories - create a store category

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

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

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

Responses

🟢200OK

application/json

Paginated store categories returned successfully. Permission references are public names only; backend-internal role, tag, user, combination, and default purchase status IDs are not returned.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🔴500Server Error

🔴502Bad Gateway

curl --location 'https://sgtr-integration.returning.ai/apis/categories?skip=undefined&limit=20&sort=displayOrder%3Aasc&fields=name%2CdisplayOrder%2CdefaultPurchaseStatusID&search=keyword%3Apremium&filter=isArchived%3Afalse&userID=650906d314a3e564c56f3403' \ --header 'Authorization: Bearer XXXXXX'

{ "meta": { "status": "success", "statusCode": 200, "skip": 0, "limit": 20, "total": 3 }, "message": "Read categories success.", "data": [ { "_id": "67bc22b591b5284096627c6c", "communityID": "6502c97314a3e564c5bbfa84", "name": "Category 3", "coverImage": null, "shouldShowCover": false, "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 }, { "type": "role_combination", "permission": { "roles": [], "tags": [], "users": [], "combination": [ { "type": "role", "values": [ "all", "Professional", "Master" ] } ], "isSelectAll": false }, "purchaseLimit": { "isEnabled": false, "quantity": 1, "intervalCount": 1, "intervalUnit": "months" }, "accessLevel": "view-only", "isEnabled": true } ], "defaultPurchaseStatus": "Pending", "i18n": { "isTranslationEnabled": true, "nameTranslations": [ { "locale": "de", "label": "de", "content": "Kategorie 3", "isAiGenerated": true, "translationConfigHash": "f6fac99b4c760b307dd010711bb714a4be44a75e32f39bddc4197d99331c2222" } ] }, "createdAt": "2025-02-24T07:41:41.053Z", "updatedAt": "2026-05-25T05:15:38.547Z" } ] }