Set a Schedule of Rates nominal account

When to use this endpoint

Use ScheduleOfRates_setNominal for CRM1’s nominal-code editor or a compatibility integration that needs the legacy three-key metadata representation.

Authentication and permissions

The request must establish tenant context with signed API credentials or a logged-in CRM session. The handler checks for the tenant database prefix rather than calling the normal login guard.

No additional page or role permission is checked. The CRM screens apply their own client-side Schedule of Rates permissions.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Positive rate ID.
`nominal_code`	String	No	Preferred trimmed account code. If omitted, legacy `nominal` is used as the code string. The first exact account-code match wins.
`nominal`	String	No	Legacy alias for `nominal_code`, not for numeric ID.
`nominal_id`	Integer string	No	Tenant account ID. If code and ID resolve to different accounts, the request fails.

Example request

FM_api('ScheduleOfRates_setNominal', [
	'id' => '430001',
	'nominal_code' => '4000',
]);

Example response

{
  "ok": 1
}

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"}`	The rate ID is absent or not positive.
`{"error":"nominal_id and nominal_code refer to different accounts"}`	Both inputs resolve, but to different tenant accounts.
`{"error":"schedule of rates does not exist"}`	The rate ID has no row.
`{"ok":1,"msg":"no change needed"}`	The resulting complete metadata JSON exactly matches the stored string.

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

Behaviour and edge cases

A valid account normalizes both ID and code. An unknown code is preserved while nominal_id and legacy nominal become 0. Blank input clears to blank code/zero IDs.
Other metadata is preserved. Invalid or scalar existing metadata is replaced with a new object.
The endpoint writes meta.nominal_id, meta.nominal_code, and meta.nominal; the last key stores the numeric ID for legacy readers.

Side effects

On change, advances last_edited and the scheduleOfRates cache marker.
Fires the tenant-configurable SOR_edit event with the rate ID. Any configured listeners run synchronously and can add integration-specific side effects.

See it in Fieldmotion

CRM1

Edit the Nominal column on the Schedule of Rates page.

CRM2

CRM2’s tax/nominal picker writes mapped metadata through ScheduleOfRate_updateData.

Related endpoints

ScheduleOfRates_setTax stores legacy tax display values.