Update one mapped Schedule of Rates field

When to use this endpoint

Use ScheduleOfRate_updateField only for a generic one-field bulk edit. CRM2’s current Schedule of Rates page normally uses ScheduleOfRate_updateData.

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 page or role-permission check.

All reads and writes use the authenticated tenant. The CRM screens apply client-side Schedule of Rates permissions, but those controls are not repeated by this endpoint.

Parameters

Parameter	Type	Required	Description
`field`	Mapped field name	Yes	One field from the shared map. Practical writable names are `name`, `code`, `stockUsed`, `cost`, `lastEdited`, `description`, `meta`, `metaNominal`, `metaNominalID`, `metaNominalCode`, `metaTaxTypeID`, `assetTypes`, `labourUsed`, `priceBands`, `archived`, and `metaCustomerCosts`. `taxType` is layout-only and is not safe here.
`val`	Mixed	Yes	One replacement applied to every found ID. Numeric types are converted; arrays/objects in text or JSON fields are JSON-encoded.
`id / ids`	Integer string or native array	Yes	`id` takes precedence. Values are integer-converted; JSON array text is not decoded.

Example request

$result = FM_api('ScheduleOfRate_updateField', [
	'ids' => ['430001', '430002'],
	'field' => 'archived',
	'val' => 1,
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id": "430001", "archived": "0"},
    {"id": "430002", "archived": "0"}
  ]
}

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: field"}`	`field` is absent.
`{"error":"missing or invalid parameter: val"}`	`val` is absent.
`{"error":"missing or invalid field"}`	The map does not contain the supplied name.
`{"error":"missing or invalid parameter: id/ids"}`	Neither ID key is present.
`{"ok":"1","warning":"no change required"}`	No target exists or every found row already has the requested value.

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 map exposes the primary key. Passing field=id attempts to renumber matching rows and can collide with another primary key. Do not use it. The composite taxType entry also has no direct column and can produce runtime errors.

Missing IDs are omitted. Existing rows whose value is unchanged are not updated.
A changed row receives current last_edited. Selecting field=lastEdited cannot preserve the submitted timestamp because the helper appends a second current-time assignment. JSON metadata fields are updated row by row; direct columns can be updated together.
The response’s oldData contains the raw selected database column, so nested metadata updates return the complete old meta string.

Side effects

Advances the schedule_of_rates cache marker and writes one generic audit entry for the changed ID set.
Does not fire SOR_edit, so configured Schedule of Rates listeners are not notified.

See it in Fieldmotion

CRM1

No direct production CRM1 caller was found.

CRM2

No direct production CRM2 caller was found; the current page uses ScheduleOfRate_updateData for single and bulk edits.

Related endpoints

ScheduleOfRate_updateData is the event-aware CRM2 update route.