Replace stock-supplier relationships

When to use this endpoint

Use StockSupplier_setSuppliers to save the complete Supplier list from a Stock editor. The payload is a replacement snapshot, not a patch.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler calls the normal login guard but performs no additional Suppliers-page, stock, purchasing, role, create, edit, or delete permission check.

All records are selected from the authenticated tenant. CRM1 and CRM2 hide some controls through client-side permissions, but these endpoints do not repeat those UI checks.

Parameters

Parameter	Type	Required	Description
`id`	Integer-compatible	Yes	Stock item ID. It is integer-converted but not checked for existence.
`suppliers`	Native array of objects	Yes	Replacement rows. Each object is read as `id` (supplier ID), `name`, `cost`, and `price`. This must be a native request array, not a JSON string.

Example request

$result = FM_api('StockSupplier_setSuppliers', [
	'id' => '8201',
	'suppliers' => [[
		'id' => '488104',
		'name' => 'Northshore Components',
		'cost' => '12.50',
		'price' => '18.75',
	]],
]);

Example response

{"ok":1}

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"}`	`id` is absent. Zero is accepted if it is present.
`{"error":"missing or invalid parameter: suppliers"}`	`suppliers` is absent.
`Runtime/type error after existing rows were removed`	`suppliers` is not an array in PHP versions that reject `count()` on that value.
`{"ok":1} after an invalid empty insert`	An empty array causes the delete first, then constructs an INSERT with no values; the database result is ignored.

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

Behaviour and edge cases

Every supplied item creates a fresh row with the stock ID, integer-converted supplier ID, name, float-converted cost/price, and current Unix edit timestamp.
Part number, quantity, and location are not accepted by this replacement route and are lost when an old relationship is replaced.
Neither the stock ID nor supplier IDs are checked for existence, active state, or deletion state. Duplicate suppliers are accepted.
The endpoint does not return newly generated relationship-row IDs.

Side effects

Physically deletes all stock_suppliers rows for the supplied stock ID, then inserts the replacement list and invalidates the relationship cache.
This bespoke route does not write Core field history or tenant deletion-log rows for the removed associations.

See it in Fieldmotion

CRM1

Saving a Stock item’s Supplier list sends the full current list to StockSupplier_setSuppliers.

CRM2

CRM2’s Stock edit workflow uses the same replacement call when its Supplier list is saved.

Related endpoints

StockSupplier_getRequestedDetails reads the list before editing.
StockSupplier_createData adds one row without replacing the rest.