List store categories

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

Returns 403 if the key does not include the store permission

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

sort accepts field:asc or field:desc using sortable category fields such as displayOrder

fields is a comma-separated projection using selectable category fields

search accepts keyword:<value> or an allowed searchable field

filter accepts field:value using filterable category fields, for example isArchived:false

userID is only forwarded to the source service as a visibility filter; it does not affect partner authorization

Invalid query syntax or unsupported fields return 400

Upstream store-service failures return 502

Example — list:

{ "query": "?skip=0&limit=20&sort=displayOrder:asc&fields=name,displayOrder&search=keyword:premium&filter=isArchived:false" }

Related endpoints:

GET /stores — read store configuration

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

GET /products — list active store products

GET /products/{productID} — read a single store product

What it is for: List store categories in the community store catalog. Use this to organize products into customer-facing store sections.
How to use it: Send a GET request to /categories with the request body, query parameters, or multipart fields shown below. Partner API key required when this surface is enabled for the community. Confirm gateway access before using in production.
Successful response: HTTP 200. The body follows the endpoint schema; many integration endpoints wrap the useful payload under data with status and message.
Common error states:

400 invalid request body, query, ObjectId, pagination, file format, or missing required field.

401 missing, invalid, expired, or insufficient API key/token.

403 key is valid but cannot access this community/channel/user/resource, where supported by the service.

404 target resource, route, or community-scoped record was not found.

409 duplicate or conflicting state for create/update operations, where applicable.

500 unexpected Returning.AI service error.

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

{ "meta": { "status": "success", "statusCode": 200, "skip": 0, "limit": 20, "total": 3 }, "message": "Read categories success.", "data": [ { "_id": "507f1f77bcf86cd799439021", "communityID": "6502c9e514a3e564c5c09c0a", "name": "Premium Rewards", "coverImage": "https://example.com/category.png", "shouldShowCover": true, "isArchived": false, "viewType": "full", "displayOrder": 0, "categoryPermission": [], "defaultPurchaseStatusID": "650906d314a3e564c56f3450", "createdAt": "2026-04-28T00:00:00.000Z", "updatedAt": "2026-04-28T00:00:00.000Z" } ] }

Request

Responses