Fieldmotion API Getting started

Work areas and stock categories

Add one stock item to a category

POST /a/StockCategory_addStock

Append one verified stock record without replacing other category members.

When to use this endpoint

StockCategory_update is the replacement alternative. Use this call when you have one existing stock item and want to preserve every other member.

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

ParameterTypeRequiredDescription
stock_idInteger-compatibleYesOne positive integer ID of an existing non-deleted tenant stock item.
cat_idInteger-compatibleYesOne positive integer ID of an existing non-deleted tenant category.

Example request

$result = FM_api('StockCategory_addStock', ['stock_id'=>'71','cat_id'=>'1042']);

Example response

{"ok":1}

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: stock_id"}stock_id absent.
{"error":"missing or invalid parameter: cat_id"}cat_id absent.
{"error":"stock category does not exist"}Category missing.
{"error":"stock item does not exist"}Stock row missing.

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

Behaviour and edge cases

  • Uses shared membership normalization, preserving other positive members. Adds only if absent.
  • Duplicate membership returns {ok:1,warning:"item was already in category"}. Even that no-op refreshes the stock item’s category summary and edit metadata.
  • 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.
  • Both IDs must be positive integers referring to non-deleted rows. No admin-only guard or configured category event is applied.
  • 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.
  • 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

  • When newly added, updates category membership and last_edited, invalidating stockcategorys cache.
  • Rebuilds each affected stock item’s category_ids as JSON text containing string IDs and categories as comma-separated names, from all current category memberships. Advances stock last_edited and sets edited_uuid to the endpoint name; invalidates stocks cache.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found for this endpoint. The legacy Stock Categories screen uses StockCategory_get and StockCategories_listByParent.

CRM2

No direct CRM2 caller was found for this endpoint. CRM2 Stock Categories uses mapped StockCategory_getRequestedDetails reads and generic create/update/delete helpers.

Related endpoints