List Store categories
GET
/v1/categories
What this endpoint does
INFO
NOTE
Quick start
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
{pathParameter} and use the query parameters documented below.Success and readback
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
Errors and recovery
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
Gotchas
Next steps
Request
Query Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/categories?skip=undefined&limit=20&sort=displayOrder%3Aasc&fields=name%2CdisplayOrder%2CdefaultPurchaseStatusID&search=keyword%3Apremium&filter=isArchived%3Afalse&userID=650906d314a3e564c56f3403' \
--header 'Authorization: Bearer XXXXXX'Response Response Example
200 - Success Example
{
"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"
}
]
}Modified at 2026-08-08 01:52:22