Create a legacy stock category

When to use this endpoint

Create the category with optional parent and initial membership. Use StockCategories_listByParent for parent choices.

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.

Creation requires client-admin permission bit 1; lack of permission returns a JSON error.

Parameters

Parameter	Type	Required	Description
`name`	String	Yes	Trimmed nonempty category name, maximum 80 characters; duplicate names are allowed.
`parent_id`	Nonnegative integer	No	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.
`stock`	CSV, JSON array text or native array	No	Replaces the full membership. Normalizes positive integers, deduplicates and sorts numerically; empty clears membership. Every retained positive ID must identify non-deleted tenant stock.

Example request

$result = FM_api('StockCategory_add', ['name'=>'Parts', 'parent_id'=>'0']);

Example response

{"ok":1,"id":1042}

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: name"}`	Missing/blank creation name or invalid supplied update name.
`{"error":"parameter too long: name. max length 80 characters"}`	Name exceeds 80 characters.
`{"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":"stock item does not exist"}`	Normalized membership contains a missing/deleted stock ID.
`{"error":"inventory write failed"}`	Checked tenant persistence failed and rolled back.
`{"error":"no permission to access api"}`	Authenticated caller is not a client admin.

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 login and client-admin permission. Uses parent_id; id and unrecognized keys are ignored.
Initial membership is normalized, validated and synchronized with stock summaries, rather than stored as unverified text. Omitting stock uses the schema default (null).
Returns a checked insert ID as a JSON number. Stamps current server datetime; no name uniqueness check.
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

Inserts the category and invalidates stockcategorys cache.
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.
Fires configured StockCat_new handlers after commit; downstream effects depend on tenant configuration.

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.