Get store category by ID - Returning.AI-dev

Returns one store category from the API-key's community by category ID, with optional field projection.

Use this when a partner integration needs category detail for a storefront category page, breadcrumb, or category-specific product listing.

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:

categoryID must be a valid category identifier accepted by the source store service

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

Missing categories return 404

Upstream store-service failures return 502

Example - read:

// Reads one category with readable public response fields.
{ "path": "/categories/67bc22b591b5284096627c6c", "query": "?fields=name,displayOrder,defaultPurchaseStatus" }

Related endpoints:

GET /categories - list store categories

POST /categories - create a store category

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

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

Responses

🟢200OK

application/json

Store category 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

🟠404Record Not Found

🔴500Server Error

🔴502Bad Gateway

{ "meta": { "status": "success", "statusCode": 200 }, "message": "Read category 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" } }