Stock inventory, storage and bundles
Split an existing inventory row into batch or serial reference rows
/a/StockInventory_addReference
Split an existing inventory row into batch or serial reference rows.
When to use this endpoint
Use from Stock Inventory's Add Reference Number action on an existing balance. This mutates inventory records, not warehouse stock; inspect all resulting rows before retrying.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. These handlers perform no additional stock, finance, page-role, department or owner check; UI button permissions are not server authorization.
Data is scoped to the authenticated tenant. Session CSRF, signed-request checks and account routing still apply. No stockTracking feature gate is enforced in these handlers.
Requires tenant upgrade 796: stock bundle, storage and inventory tables must have deleted/ddate columns before deploying these handlers.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible scalar | Yes | Positive integer existing inventory ID; the row is locked for the full split. |
reference | String for batch; native string array for serial | Yes | Non-blank batch string, or non-empty dense native string array for serial mode. Serial values are trimmed and must be unique within the request. Each value is limited to 100 characters; JSON text is not decoded. |
type | Integer-compatible scalar | Yes | Exactly 0 (batch) or 1 (serial); other values are rejected. |
qty | Positive finite numeric scalar | Yes | Positive finite requested quantity; batch mode preserves fractions and requires qty<=saved balance. Serial mode requires this parameter but uses the reference count, which must not exceed the saved balance. |
Example request
$saved = FM_api('StockInventory_addReference', ['id'=>'1042','type'=>'0','qty'=>'2','reference'=>'BATCH-004']);Example response
{"ok":1,"id":1088}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 omitted. |
{"error":"missing or invalid parameter: reference"} | reference omitted. |
{"error":"missing or invalid parameter: type"} | type omitted. |
{"error":"missing or invalid parameter: qty"} | qty omitted. |
{"error":"no inventory available"} | No active row or its saved quantity is non-positive. |
{"error":"quantity exceeds available inventory"} | Batch quantity or serial count exceeds saved balance. |
{"error":"duplicate serial reference"} | Serial list duplicates a value after trimming. |
{"error":"inventory write failed"} | A primary write/history insert fails; all split changes roll back. |
{"error":"stock deletion could not be recorded"} | Full serial source deletion audit fails; clones and source changes roll back together. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Batch quantities preserve decimals. A smaller quantity reduces the original and creates a cloned row; a quantity equal to the saved balance changes only the reference. Excessive, non-positive and non-finite quantities are rejected before writing.
- Serial mode creates one qty=1 clone per trimmed, unique non-blank reference. The count cannot exceed the saved balance; a fractional remainder is preserved. Existing references on other rows are not checked for uniqueness.
- A full serial split soft-deletes the exhausted source with a checked tenant deletion audit, retaining its original fields for history. Active detail/grid reads exclude it, including isAll. Partial splits retain the source with its fractional remainder.
- Inventory writes and Core_log-compatible history are one checked transaction with a locked source. A failed primary write/history insert rolls back the complete split.
- Clones retain source data including cdate and metadata, with fresh server last_edited. No warehouse in_stock or movement history reconciliation is performed.
- Batch split returns the created id; batch rename returns prior reference in oldData (or a no-change warning). Serial mode returns ok and the source's previous qty in oldData, not the created serial IDs.
- Clones do not inherit deleted/ddate. Full serial deletion also advances the catalog item's last_edited sync marker so mobile inventory references refresh; catalog business fields and warehouse quantities are unchanged.
Side effects
- Creates/updates inventory rows, server edit timestamps, history and cache markers in one tenant transaction. Full serial splits soft-delete and audit the source and advance its catalog sync marker. No notification or configured event.
See it in Fieldmotion
CRM1
No direct CRM1 caller was found for this exact endpoint; the legacy Stock page uses its separate catalog/container APIs.
CRM2
Open Stock Inventory → Add Reference Number. Choose Batch or Serial; the UI trims/deduplicates serial lines and warns about count mismatch, but those checks are not server validation. Filter Network for StockInventory_addReference.
Related endpoints
StockInventory_getRequestedDetailsreads stored mapped values; an omitted ID can retrieve all active tenant rows.StockInventory_createDatacreates a new inventory row rather than changing physical warehouse stock.