Fieldmotion API Getting started

Stock catalog fields and lookups

Rename a stock item

POST /a/Stock_setName

Change one stock name, retaining whitespace and allowing duplicate names.

When to use this endpoint

Use for a legacy inline rename or a reviewed duplicate-name repair. This does not change stock code, quantities or names copied into existing documents.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. This handler requires both a user identity and tenant context; it adds no stock-page, finance or administrator permission check.

All queries use the authenticated tenant. API signing and session CSRF checks still apply; see Getting started.

Parameters

ParameterTypeRequiredDescription
idInteger-compatible stringYesStock ID converted with intval; must be at least 1.
valStringYesNon-falsey value required; blank and string "0" are rejected, whitespace-only names are accepted. Not trimmed. Maximum 80 bytes, not 80 Unicode characters.

Example request

$result = FM_api('Stock_setName', ['id'=>'1042', 'val'=>'Filter cartridge']);

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: id"}Missing/nonpositive id.
{"error":"stock with that ID does not exist"}No non-deleted stock row.
{"error":"no val parameter supplied, or it is blank"}val missing/null/falsey, including string "0".
{"error":"parameter too long: val"}strlen(val) exceeds 80 bytes.
{"ok":1,"warning":"No change needed"}Stored name strictly equals string-normalized input; skips history/timestamp/event.
{"error":"stock catalog write failed"}A primary write or required history insert fails; the transaction rolls back.
{"error":"stock catalog read failed"}A checked read fails; a normalization or write transaction is rolled back.
{"error":"stock catalog transaction failed"}Transaction start or commit fails; no success is returned.
{"error":"stock catalog operation failed"}Unexpected database/runtime failure during the transaction.

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

Behaviour and edge cases

  • Locks a non-deleted target; archived stock remains editable. No duplicate-name check or whitespace trimming.
  • Text comparison is strict, so numerically equivalent but differently spelled names are still saved. No code change or existing-document backfill.
  • Checked name write and field history commit before Stock_edit. No client-admin permission or stock naming setting.
  • No direct mobile caller was found in the current app JavaScript or m/www intermediary. The app receives stock through syncDownloads, which selects non-deleted stock by edit timestamp; these calls are not the app synchronization protocol.

Side effects

  • On change, writes name, server last_edited, edited_uuid=Stock_setName and checked history; invalidates stocks cache.
  • Configured Stock_edit runs after commit; no physical stock movement.

See it in Fieldmotion

CRM1

Click a name cell on Stock and blur the 80-character input. CRM1 sends id/val; its character-count check is not the server’s byte limit. The integration duplicate-name helper also uses this route for suffixes.

CRM2

The QuickBooks duplicate-name widget calls Stock_setName to append suffixes. Ordinary Stocks editing uses mapped fields rather than this narrow setter.

Related endpoints