Work areas and stock categories
Delete a legacy category and reparent children
/a/StockCategory_delete
Remove one category node while moving its immediate children to its previous parent.
When to use this endpoint
StockCategories_listByParent reloads the subtree using the returned pid after deleting a node; the stock items themselves remain.
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. |
Example request
$result = FM_api('StockCategory_delete', ['id'=>'1042']);Example response
{"ok":1,"pid":"0"}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":"category deletion requires a single id only"} | Extra recognized deletion filters supplied. |
{"error":"this stock category does not exist"} | No active category matches. |
{"error":"inventory deletion could not be recorded"} | Audit failed; tenant writes roll back. |
{"error":"inventory write failed"} | 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 one positive scalar id. Recognized extra mapped filters and arrays/bulk IDs are rejected; deletion cannot silently include unrelated categories.
- A missing or already deleted ID returns this stock category does not exist; success returns its prior parent as pid (string).
- Reparents immediate active children to the previous parent and advances their timestamps. If that legacy ancestor chain is missing/cyclic, reparents to root instead.
- Sets deleted=1, ddate to Unix time and last_edited to server datetime; records the original row in deletes under mobile key stockcategorys with app_id=0. Repairs affected active stock summaries and clears tenant stockcat mappings in the same transaction.
- 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.
- Global stockcat upload-queue cleanup occurs after the tenant commit, before StockCat_edit; a failed post-commit task returns success plus a warning, not a rollback.
- 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/wwwintermediary 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
- Soft-deletes and audits the category, reparents children, removes tenant accounting links and refreshes stock summaries.
- Rebuilds affected active stock items’ category_ids as JSON text containing string IDs and categories as comma-separated names. Advances stock last_edited and sets edited_uuid to the endpoint name; invalidates stocks cache. No stock quantity movement occurs.
- After commit, clears global stockcat upload entries and fires configured StockCat_edit.
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_listretrieves a flat category projection.StockCategory_getRequestedDetailsuses the mapped CRM2 field names.