Read selected raw price bands

When to use this endpoint

Use for raw cached-object lookups or exports. The supplied field projection is exact: id is not automatically added.

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
`ids`	Native array or JSON array text	Yes	Members are integer-coerced and deduplicated. Empty arrays are rejected; zero/negative values are not rejected individually but normally have no row.
`fields`	Native array or JSON array text	No	Allowed raw names: id, name, order_num, is_relative, relative_multiple, cdate, last_edited. Unknown names are ignored; camelCase aliases are not accepted. Omission selects all seven; a supplied projection with no recognized names is an error. Duplicate requested names are removed.

Example request

$bands = FM_api('PriceBands_getById', ['ids'=>json_encode(['1042', '1043']), 'fields'=>json_encode(['id', 'name', 'relative_multiple'])]);

Example response

[{"id":"1042","name":"Trade","relative_multiple":"0.9"}]

Raw fields are id, name, order_num, is_relative, relative_multiple, cdate and last_edited. Database numerics normally remain JSON strings; name can be null. Both timestamps store Unix seconds, not formatted dates.

Returns a bare array, omitting nonexistent IDs; empty results are []. A failed database read can return false.

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: ids"}`	ids is missing or not an array after JSON decoding.
`{"error":"no ids in list"}`	The decoded/native ID array is empty.
`{"error":"no fields selected"}`	A supplied fields value contains no recognized raw names.
`false`	Database read fails.

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

Behaviour and edge cases

No ordering, paging, name filtering, active/archive filtering or price calculation is applied. Input ID order does not determine output order.
No priceBands tenant feature check or additional role restriction; the table has no soft-delete column.
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.

Side effects

Read-only; no history, timestamp update, pricing recalculation or cache invalidation.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found; its price-band dropdowns use PriceBands_list.

CRM2

Open a stock or schedule-of-rates pricing workflow for a customer assigned to a band; the PriceBand cached-object loader requests PriceBands_getById. The export widget also reads selected IDs/fields through this route.

Related endpoints

PriceBand_getRequestedDetails returns mapped fields and automatically adds id.
PriceBands_list reads all bands with a smaller default projection.