Price bands and stock pricing
Patch mapped price-band fields
/a/PriceBand_updateData
Patch one band, or apply the same mapped values atomically to a native array of IDs.
When to use this endpoint
Use for a multi-field edit or bulk multiplier change. Every requested ID must exist; the batch either commits all changes/history or returns an error.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session; all normal calls use that tenant. These handlers do not enforce an additional role or finance-page permission.
Use strings for signed numeric values, including values inside native arrays. Only JSON-encode parameters explicitly described as JSON text; see Getting started.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible scalar or native array | Yes | One positive integer ID or a nonempty native array of positive IDs; duplicates are removed. JSON text is not decoded as a bulk array. All IDs are checked before any row is changed. The ids alias is not accepted. |
name | String | Required on creation; optional on update | Trimmed nonblank name, at most 64 bytes. Duplicate names are accepted; mapped calls accept "0" while legacy new/setName reject it. Omitted update names are preserved. |
orderNum / isRelative | Integer-compatible scalars | No | Integer-coerced. Creation defaults to 0; omission on updates preserves values. Negative order and modes other than 0/1 are not prohibited; other modes fall back to base price in Stocks_getPrice. |
relativeMultiple | Finite numeric scalar | No | Numeric text/number is float-coerced; nonnumeric, blank and nonfinite supplied values are rejected. No sign/range restriction. Creation defaults to 1; omission on update preserves it. 0.9 means 90% of base price. |
cDate | Integer-compatible Unix seconds | No | Optional caller-supplied creation timestamp. Creation defaults to current server Unix time; supplied values are integer-coerced and mapped updates can change it. |
lastEdited | Ignored legacy input | No | Server-owned edit timestamp. Supplied values cannot suppress or backdate the edit; changed rows use current server Unix time. No-op edits preserve the existing timestamp. |
Example request
$result = FM_api('PriceBand_updateData', ['id'=>['1042', '1043'], 'relativeMultiple'=>'0.9']);Example response
{"ok":1}Changed scalar and native-array calls return numeric ok=1. If all recognized values are already equal, returns {"warning":"No Change."}; an empty ID array or missing target is an error, not success.
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, invalid/nonpositive, or an empty native array. |
{"error":"price band does not exist"} | At least one supplied valid ID has no row; no changes are committed. |
{"error":"no updated fields."} | No recognized non-null writable field is supplied; lastEdited alone is not a patch. |
{"warning":"No Change."} | The normalized patch changes no field on any target. |
{"error":"name too long. max length 64"} | Trimmed name exceeds 64 bytes. |
{"error":"missing or invalid parameter: relativeMultiple"} | A supplied multiplier is nonnumeric or nonfinite. |
{"error":"pricing write failed"} | A primary write or required history write fails; the transaction is rolled back. |
{"error":"pricing read failed"} | A checked lookup fails; nothing is committed. |
{"error":"pricing transaction failed"} | Transaction start or commit fails. |
{"error":"pricing operation failed"} | Unexpected database/runtime failure; no success is returned. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Mapped fields are
id,name,orderNum,isRelative,relativeMultiple,cDateandlastEdited; the latter five map to order_num, is_relative, relative_multiple, cdate and last_edited. - Supplied non-null writable values are validated and normalized; omitted fields are preserved. Unknown keys and internal noRecord/noRecordCustom controls are ignored. Primary IDs cannot be changed.
- Changed rows use server Unix time for last_edited; explicit lastEdited input is ignored. Existing cdate is preserved unless cDate is explicitly supplied. No-op patches do not advance the edit timestamp.
- Name is trimmed, required to be nonblank when supplied and limited to 64 bytes. Duplicate names remain allowed; no 0/1 restriction is enforced for isRelative.
- The mobile app has no direct caller for this endpoint in the searched JavaScript or
m/wwwintermediary. It downloads price bands throughsyncDownloadsinto its localpriceBandstable.
Side effects
- Invalidates price_bands cache for changed rows and records checked field history for each changed band, using its own ID. Primary writes and history commit together. No stock/customer rewrite, configured event, notification or external call.
See it in Fieldmotion
CRM1
No direct CRM1 caller was found. Settings → Finance → Price Bands uses legacy creation and individual snake_case setters instead.
CRM2
Open Settings → Finance → Price Bands and edit Name, Order, Type or Multiplier inline; filter PriceBand_updateData. The bulk multiplier action first loads selected IDs/isRelative, then sends a native id array; the UI permits only applicable relative bands.
Related endpoints
PriceBand_updateFieldsets one mapped field and returns raw oldData.PriceBand_setRelativeMultipleadvances the server timestamp on a changed multiplier.