Fieldmotion API Getting started

Price bands and stock pricing

Set one mapped price-band field

POST /a/PriceBand_updateField

Apply one mapped field value to one or several price bands and return previous raw values.

When to use this endpoint

Use for a single-field edit. Check the warning response and oldData rather than assuming all supplied IDs existed.

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
id / idsInteger-compatible scalar or native arrayYesid takes precedence over ids. A positive integer scalar or nonempty native array of positive IDs is required; duplicates are removed. JSON text is not decoded. Every target must exist.
fieldMapped field nameYesWritable mapped names: name, orderNum, isRelative, relativeMultiple and cDate. id and lastEdited are not writable through this route.
valNon-null scalarYesNon-null scalar. Name must be a trimmed nonblank string of at most 64 bytes. Integer fields use intval; relativeMultiple must be finite numeric and cannot be blank. Zero is accepted.

Example request

$result = FM_api('PriceBand_updateField', ['ids'=>['1042'], 'field'=>'orderNum', 'val'=>'2']);

Example response

{"ok":1,"oldData":[{"id":"1042","order_num":"0"}]}

oldData contains id plus the raw stored column for all requested rows, including unchanged rows. Rows are read in ascending ID order, not input order. A missing target rejects the whole request.

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: field"}field omitted.
{"error":"missing or invalid parameter: val"}val omitted or null.
{"error":"missing or invalid field"}Unrecognized, nonscalar or read-only field, including id/lastEdited.
{"error":"missing or invalid parameter: id/ids"}No valid positive identifier, or empty array.
{"error":"price band does not exist"}At least one supplied valid ID has no row; no changes commit.
{"ok":"1","warning":"no change required"}All normalized values equal the stored values.
{"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

  • Comparison uses normalized numeric values; equivalent numeric wire values do not cause unnecessary writes. Name is compared after trimming.
  • Writes and required history are checked in one tenant transaction. Every changed row advances last_edited to current Unix time; no-op rows preserve it. cdate changes only when field is cDate.
  • No name uniqueness, extra role or finance-feature guard; multiplier sign/range and isRelative modes are not otherwise restricted.
  • 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

  • Each changed band gets its own checked field-history record and server edit timestamp. The price_bands cache is invalidated. A failed write/history entry rolls back all target changes; no configured event, customer/stock recalculation, notification or external request.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. Settings → Finance → Price Bands uses legacy creation and individual snake_case setters instead.

CRM2

No direct CRM2 caller for this endpoint was found. The finance display widget configures all inline edits as PriceBand_updateData; filter that request when editing Name or Order.

Related endpoints