Set fixed or relative pricing mode

When to use this endpoint

Use this legacy single-field setter for an existing band. The CRM2 mapped update route uses camelCase field names instead.

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	Yes	Converted with `intval`; must be positive. Zero, omission and invalid text are rejected; an absent row is not created.
`is_relative`	Integer-compatible scalar	No	Defaults to zero. UI values are 0 (fixed item override) or 1 (base price multiplied by relative_multiple), but the handler accepts other integers.

Example request

$result = FM_api('PriceBand_setIsRelative', ['id'=>'1042', 'is_relative'=>'1']);

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 coerced ID is less than one.
`{"error":"price band does not exist"}`	The positive ID has no tenant row, or its lookup fails.
`{"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

Legacy coercion and ID/name guards run before login; checked persistence validates the normalized values and locks the tenant row.
Only writes when the normalized value differs from the stored value. No change still returns numeric ok=1 without advancing the timestamp.
Values other than 0 or 1 fall back to base stock price in Stocks_getPrice; acceptance does not establish another supported pricing mode.
No server finance-feature setting is checked; the CRM2 priceBands feature and edit-permission checks are UI restrictions.
The mobile app has no direct caller for this endpoint in the searched JavaScript or m/www intermediary. It downloads price bands through syncDownloads into its local priceBands table.
A failed primary/history write returns an error and rolls back the transaction. The unchanged-value response remains numeric ok=1.

Side effects

On change, updates the field and server Unix edit timestamp, invalidates price_bands cache and records checked field history. Writes/history commit atomically. No stock/customer rewrite, configured event, notification or external request.

See it in Fieldmotion

CRM1

Open Settings → Finance → Price Bands and edit pricing type inline. Filter PriceBand_setIsRelative; the screen sends is_relative as 0 or 1.

CRM2

No direct caller for PriceBand_setIsRelative was found. Settings → Finance → Price Bands uses PriceBand_updateData for mode/multiplier edits and mapped widgets for other fields.

Related endpoints

PriceBand_updateData patches several mapped fields with checked persistence.
PriceBand_get reads one raw row, including integer timestamps.
PriceBand_getRequestedDetails reads mapped fields for one or several IDs.