Set Schedule of Rates tax metadata

When to use this endpoint

Use ScheduleOfRates_setTax for CRM1’s legacy tax editor. CRM2 normally stores the tax-type ID and nominal relationship through mapped metadata instead.

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.
`tax_rate`	Number	Yes	Floating-point percentage stored as `meta.tax_rate`.
`tax_type`	String	Yes in practice	Display/category value stored as `meta.tax_type`. Omission is not validated before string escaping and can produce runtime notices/errors.

Example request

FM_api('ScheduleOfRates_setTax', [
	'id' => '430001',
	'tax_rate' => 20,
	'tax_type' => 'VAT',
]);

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 ID is absent or not positive.
`{"error":"missing parameter: tax_rate"}`	`tax_rate` is absent.
`{"error":"schedule of rates does not exist"}`	The 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

Tax values are not resolved against account categories. The endpoint trusts the supplied percentage and display value, and it does not set meta.tax_type_id. Use the CRM2 mapped tax picker when relational IDs are required.

Other metadata keys are preserved. Invalid/blank existing metadata is replaced with a new object.
ScheduleOfRates_getDT and export read these modern keys. The older ScheduleOfRates_get/SchedulesOfRates_getById derived tax_rate reads legacy meta.tax instead and therefore reports zero.

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

The create flow and Tax column call this endpoint with a rate and category display value.

CRM2

CRM2 uses ScheduleOfRate_updateData with metaTaxTypeID and nominal metadata.

Related endpoints

ScheduleOfRates_setNominal stores the nominal account metadata.