Update Store category

What this endpoint does

Change one category while preserving fields that were not submitted.

INFO

Workflow

Update category → read category

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

{
  "displayOrder": 20
}

Success and readback

Branch on: meta.code = CATEGORY_UPDATED

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "CATEGORY_UPDATED"
  },
  "message": "Update Store category successfully",
  "data": {
    "_id": "cat_agent_01",
    "name": "Agent Test Rewards",
    "displayOrder": 20
  }
}

CHECK

Readback

Read back with GET /v1/categories/{categoryID}; submitted fields change and omitted fields remain unchanged.

Errors and recovery

Branch on meta.code, never message text.

HTTP	Machine code	What the caller should do	Retry?
400	`VALIDATION_FAILED`	Repair errors[].	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
404	`STORE_RESOURCE_NOT_FOUND`	Refresh the category ID.	After refreshing the ID
500	`INTERNAL_ERROR`	Retry with exponential backoff and the same request context, then escalate.	Yes, with backoff

Retry safety

WARNING

Exact retry

The same partial update is safe to retry after readback.

Gotchas

Avoid this mistake

Next steps

Read Store category

Continue with the next operation in the connected Store lifecycle.

curl --location --request PUT 'https://api.returning.ai/v1/categories/67bc22b591b5284096627c6c' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "name": "VIP Rewards", "coverImage": "https://example.com/category.png", "shouldShowCover": true, "isArchived": false, "viewType": "full", "displayOrder": 10, "categoryPermission": [ { "type": "role", "permission": { "roleNames": [ "VIP Member" ], "tagNames": [ "Early Access" ], "usernames": [ "alex" ], "combination": [], "isSelectAll": false }, "purchaseLimit": { "isEnabled": true, "quantity": 1, "intervalCount": 1, "intervalUnit": "months" }, "accessLevel": "full-access", "isEnabled": true } ], "defaultPurchaseStatusName": "Pending", "i18n": { "isTranslationEnabled": false, "nameTranslations": [] } }'

{ "meta": { "status": "success", "statusCode": 200 }, "message": "Update category success.", "data": { "_id": "67bc22b591b5284096627c6c", "communityID": "6502c97314a3e564c5bbfa84", "name": "VIP Rewards", "coverImage": "https://example.com/category.png", "shouldShowCover": true, "isArchived": false, "viewType": "full", "displayOrder": 10, "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 } ], "defaultPurchaseStatus": "Pending", "i18n": { "isTranslationEnabled": false, "nameTranslations": [] }, "createdAt": "2025-02-24T07:41:41.053Z", "updatedAt": "2026-05-25T05:15:38.547Z" } }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps