Create a stock-supplier relationship

When to use this endpoint

Use StockSupplier_createData when creating one association with mapped fields. To replace all suppliers for one stock item in the same legacy shape used by the Stock editor, use StockSupplier_setSuppliers.

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 or array	No	Ignored for creation; a relationship-row ID is assigned.
`name`	String	Yes	Relationship label, normally copied from the stock item name.
`stockID`	Integer-compatible	No	Stock item ID. The endpoint integer-converts it but does not verify that the stock item exists.
`supplierID`	Integer-compatible	No	Supplier ID. The endpoint integer-converts it but does not verify that an active supplier exists.
`locationID, qty`	Integer-compatible	No	Optional location and quantity values, converted with `intval()`.
`cost, price`	Numeric-compatible	No	Per-unit cost and price, converted with `floatval()`.
`partNumber`	String	No	Supplier-specific part number.
`lastEdited`	Unix timestamp or date string	No	Stored as a Unix timestamp. Creation defaults to the current server time; a nonnumeric value is parsed with `strtotime()`.

Example request

$relation = FM_api('StockSupplier_createData', [
	'name' => 'Northshore Components',
	'stockID' => '8201',
	'supplierID' => '488104',
	'cost' => '12.50',
	'price' => '18.75',
	'partNumber' => 'NS-8201',
]);

Example response

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

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"}`	Required `name` is absent or empty.
`{"error":"missing or invalid parameters."}`	No writable mapped value remains.
`Validation error naming a field`	A mapped date/value conversion fails.

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

Behaviour and edge cases

The table has no soft-delete behavior. A new physical relationship row is inserted.
Omitted optional fields retain their database defaults. lastEdited defaults to the current server Unix timestamp.
The endpoint does not enforce uniqueness for a stock/supplier pair, so repeated creates can produce duplicate relationships.

Side effects

The shared writer invalidates the stock_suppliers cache and records field-addition entries in Core history.

See it in Fieldmotion

CRM1

No direct CRM1 production caller was found; CRM1 normally saves the whole Stock supplier list through StockSupplier_setSuppliers.

CRM2

CRM2’s generic mapped widgets can call this single-row route, while the Stock editor primarily uses the replacement endpoint.

Related endpoints

StockSupplier_updateData changes an existing relationship row.
StockSupplier_getRequestedDetails reads mapped relationship rows.