When to use this endpoint

Use after selecting stock and category IDs. This changes membership incrementally; Stock_updateData categoryIDS replaces the selection.

Authentication and permissions

Authenticate with a signed API key or a logged-in CRM session on the account’s routed host. API keys act as their owner; session calls require dispatcher CSRF protection where configured. IDs address the authenticated tenant.

These stock handlers do not add a Stock page-action or CRM2 role check, and the dispatcher has no Stock/Stocks TeamAccess object mapping. CRM2 screen controls are separate from this shared API contract; their roles must not be assumed to apply to CRM1.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesPositive stock catalogue ID. It is not a stock-container row ID, category ID or supplier ID.
cidsNative array or JSON array textYesCategory IDs, not names. Positive integer-compatible entries are retained.

Example request

$result = FM_api('Stock_addToCategories', ['id'=>'18', 'cids'=>json_encode(['7','9'])]);

Example response

{
  "ok": 1
}

Application errors can use HTTP 200. Inspect error/warning fields; database numeric values can be strings unless this handler explicitly converts them.

Errors and unusual responses

ResponseCondition
{"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"}ID is absent or integer-converts below 1.
{"error":"missing or invalid parameter: cids"}No usable positive category IDs.

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 undeleted stock item and positive category IDs. Missing/unknown categories are rejected rather than silently skipped. Empty cids is invalid.
  • Serializes membership changes using the same tenant-owner lock as category hierarchy edits. Rebuilds category stock-member lists and the item category_ids/categories mirror together; IDs are normalized, deduplicated and sorted.
  • A new member of a category already holding 8,000 items returns stock category membership limit reached. An existing member remains valid. All selected changes roll back together on failure.
  • Primary changes and stock history use a checked transaction. Failed validation/read/write/commit returns an error and rolls back open changes. Configured events/notices run after commit; a post-commit warning means the save succeeded and must not be repeated blindly.

Side effects

  • Checked category and stock mirror/cache/timestamp/history writes, then Stock_edit events.

See it in Fieldmotion

CRM1

CRM1 Stock_add calls Stock_addToCategories internally when its editor supplies JSON categories. No direct browser caller of these membership commands was found; inspect Stock_add plus its saved category results. Stock_removeFromCategories is an API/internal counterpart.

CRM2

Open Stocks in CRM2. Stock layouts derive Stock_createData, Stock_updateData and Stock_getLayoutDetails through the shared helpers; the grid calls Stocks_getDataTable. Inspect the exact function name in Network requests. Layout saves normally replace categoryIDS rather than calling these incremental membership commands.

Related endpoints

  • Stock_updateData — Update stock fields, category membership and picker values through the full mapped save.
  • Stock_get — Read the full saved stock row, with selected manufacturing metadata flattened for the legacy editor.
  • Stock_removeFromCategories — Update category membership and rebuild the stock item’s category mirror.