Stock items and catalogue maintenance
Create mapped stock
/a/Stock_createData
Create a catalogue record from CRM2 layout fields and synchronize category membership.
When to use this endpoint
Supply the layout-required name, averageCost, price and categoryIDS; use Stock_add only when its legacy code-matching/increment behavior is intended.
Authentication and permissions
Authenticate with a signed API key or a logged-in CRM session on the account’s routed host. API keys act as their owner; session calls require dispatcher CSRF protection where configured. IDs address the authenticated tenant.
These stock handlers do not add a Stock page-action or CRM2 role check, and the dispatcher has no Stock/Stocks TeamAccess object mapping. CRM2 screen controls are separate from this shared API contract; their roles must not be assumed to apply to CRM1.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
Stock fields | Mapped values | Depends on operation | Mapped names: id,name,averageCost (alias cost),cDate,ownerID,inStock,categories,categoryIDS,lastEdited,code,isArchived,amtTrigger,description,supplierID,price,notes,nominalCode,taxRate,meta,editedUUID,priceBands. Metadata projections: metaManufacturer,metaBarcode,metaManufacturerPartNo,metaSupplierPartNo,metaSuppliers,metaUnit,metaTaxRateID,metaNominalCodeID,metaNominalID,metaNominalName,customValues,metaReferrenceType. taxType is a composite picker with id,taxRate,nominalID,nominalName,nominalCode. Preserve the misspelling metaReferrenceType. |
taxType | Native picker object | No | Expands id→metaTaxRateID, taxRate→taxRate, nominalID→metaNominalID, nominalName→metaNominalName, nominalCode→nominalCode. Keep nominal IDs, codes and display names distinct. |
categoryIDS | ID list / JSON list / comma text | No | The full wrappers normalize positive IDs, deduplicate/sort, and save them as JSON strings. Unknown category IDs return an error; empty category lists remain supported. |
widgetPriceBand | Encoded JSON or mapped value | No | Alias to priceBands on full create/update; underlying JSON replaces the saved value. |
taxRate | Integer-compatible category ID | No | Full wrappers save the input as metaTaxRateID and replace taxRate with the selected account_categories.tax_rate, preserving fractions. A composite taxType object expands later in the shared helper and can supply its own percentage. |
Required values | Mapped values | Yes | name (nonempty),averageCost,price,categoryIDS are map-required. Zero cost/price are accepted; category normalization can turn an empty list into encoded [] which passes the generic presence check. |
Example request
$result = FM_api('Stock_createData', ['name'=>'Valve', 'averageCost'=>'12.5', 'price'=>'20', 'categoryIDS'=>json_encode(['7']), 'metaUnit'=>'0']);
Example response
{
"ok": 1,
"id": 18
}
Application errors can use HTTP 200. Inspect error/warning fields; database numeric values can be strings unless this handler explicitly converts them.
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"} | A required mapped field is absent/empty; the message names that field. |
{"error":"name is too long."} | Mapped name exceeds 80 characters. |
{"error":"Unable to create record"} | The generic insert fails or does not return a positive ID. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Requires name,averageCost,price,categoryIDS as before; zero prices/costs and an empty category list remain supported. cost alone does not satisfy averageCost. Layout display lifecycle fields are ignored rather than made editable.
- Top-level taxRate selects a category; its full fractional percentage is stored with metaTaxRateID. Blank/0 selects no tax; a missing positive category is rejected. taxType remains a native picker object with no-tax id=0 support.
- Primary creation, generic history and category membership/mirror changes share a transaction. Unknown categories/failed membership writes roll the new record back. Stock_new and mention notices occur only after commit.
- Primary changes and stock history use a checked transaction. Failed validation/read/write/commit returns an error and rolls back open changes. Configured events/notices run after commit; a post-commit warning means the save succeeded and must not be repeated blindly.
Side effects
- Transactional stock/category/history/cache changes; post-commit Stock_new and mention notices.
See it in Fieldmotion
CRM1
No direct CRM1 Stock_createData caller was found. CRM1 Stock creation uses Stock_add and its distinct matching/default rules.
CRM2
Open Stocks in CRM2. Stock layouts derive Stock_createData, Stock_updateData and Stock_getLayoutDetails through the shared helpers; the grid calls Stocks_getDataTable. Inspect the exact function name in Network requests. Use New Stock / layoutStockCreate; createData(table=stock) derives this exact route.
Related endpoints
Stock_updateData— Update stock fields, category membership and picker values through the full mapped save.Stock_getLayoutDetails— Read mapped stock rows while adapting price-band widgets and tax category selections.Stock_add— Create a stock item, or match/update an existing one while adding a signed warehouse quantity.