Fieldmotion API Getting started

Price bands and stock pricing

Rename a price band

POST /a/PriceBand_setName

Rename a price band without changing its other configuration fields.

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

ParameterTypeRequiredDescription
idInteger-compatible scalarYesConverted with intval; must be positive. Zero, omission and invalid text are rejected; an absent row is not created.
nameStringYesTrimmed nonempty name of at most 64 bytes; omission, blank and "0" are invalid. Duplicate names are allowed.

Example request

$result = FM_api('PriceBand_setName', ['id'=>'1042', 'name'=>'Trade retail']);

Example response

{"ok":1}

Errors and unusual responses

ResponseCondition
{"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":"missing or invalid parameter: name"}Name is missing, blank or "0".
{"error":"name too long. max length 64"}Trimmed name exceeds 64 bytes.
{"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.
  • Name is not a unique key; imports matching by name can select a different duplicate.
  • 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 Name inline. Filter PriceBand_setName; the screen sends name.

CRM2

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

Related endpoints