Fieldmotion API Getting started

Price bands and stock pricing

Set price-band display order

POST /a/PriceBand_setOrderNum

Set price-band display order 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.
order_numInteger-compatible scalarNoDefaults to zero when omitted or blank; intval coercion applies and negative values are allowed. This affects stored order, not prices.

Example request

$result = FM_api('PriceBand_setOrderNum', ['id'=>'1042', 'order_num'=>'2']);

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":"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.
  • Rows with equal order_num have no stable secondary order in the legacy table query; list routes do not sort automatically.
  • 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 Order inline. Filter PriceBand_setOrderNum; the screen sends order_num.

CRM2

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

Related endpoints