Move a category’s parent pointer

When to use this endpoint

StockCategories_listByParent reloads the tree after a move. Pre-check that the destination is not the node or one of its descendants.

Categories organize stock membership and parent/child navigation; these calls do not transfer physical stock or change quantities. Select the legacy or mapped API that matches your field names.

Authentication and permissions

Authenticate using signed API-key fields or a logged-in CRM session. All object queries use the authenticated tenant. The handler has no additional page, role or feature check unless stated below.

Sign numeric request values as strings, including nested native arrays; only JSON-encode parameters that explicitly accept JSON text. See Getting started.

Parameters

Parameter	Type	Required	Description
`id`	Positive integer	Yes	One positive integer ID of an active tenant-local record; arrays, negative numbers and SQL-like strings are rejected.
`to`	Nonnegative integer	Yes	0 is root; supplied positive parent must be active and cannot be this category, a descendant or part of a cyclic ancestor chain. Creation defaults to 0; omitted updates preserve the parent.

Example request

$result = FM_api('StockCategory_move', ['id'=>'1042','to'=>'1088']);

Example response

{"ok":1}

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"missing or invalid parameter: id"}`	Not one positive integer.
`{"error":"missing or invalid parameter: to"}`	Destination missing or not a nonnegative integer.
`{"error":"stock category does not exist"}`	No active source category.
`{"error":"stock category parent does not exist"}`	Positive parent is missing or deleted.
`{"error":"stock category parent would create a cycle"}`	Changed parent would create or enter a cyclic ancestor chain.
`{"error":"inventory write failed"}`	Checked tenant persistence failed and rolled back.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Requires an existing active category. Changed destination must be root or a valid active non-cyclic ancestor chain. Self-parenting and descendant cycles are rejected.
A changed parent updates parent_id and server-datetime last_edited, then fires StockCat_edit after commit. An unchanged parent returns ok without writes/events. Stock membership and quantities are unchanged.
Tenant row changes, membership repairs and required audit writes are checked within one transaction; a failure rolls them back and returns an error. Configured events run only after commit.
Only non-deleted categories are read or changed. No quantity, price or accounting-provider availability check is applied.
The source search found no direct caller in the mobile JavaScript app or its m/www intermediary for this endpoint.
Post-commit event failures on event-producing writes return the committed success plus warning: saved, but a configured event failed; do not repeat creation. Review the saved record before retrying.

Side effects

Updates changed parent/timestamp and invalidates stockcategorys cache; fires StockCat_edit only after commit.

See it in Fieldmotion

CRM1

Open Stock Categories and select, create, save, drag or delete a category as appropriate; filter browser Network by this endpoint’s exact function name.

CRM2

CRM2 Stock Categories uses mapped detail/create/update/delete calls instead; no direct caller found for this legacy endpoint.

Related endpoints

StockCategories_list retrieves a flat category projection.
StockCategory_getRequestedDetails uses the mapped CRM2 field names.