Fieldmotion API Getting started

Price bands and stock pricing

List raw price-band choices

POST /a/PriceBands_list

List every tenant price band with an optional raw column projection.

When to use this endpoint

Use for small price-band dropdowns or per-stock override labels. Use a table endpoint when paging is required.

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
fieldsNative array or JSON array textNoAllowed raw names: id, name, order_num, is_relative, relative_multiple, cdate, last_edited. Unknown names are ignored; camelCase aliases are not accepted. Defaults to id, name and order_num when omitted, malformed, empty, or entirely unrecognized.

Example request

$bands = FM_api('PriceBands_list', ['fields'=>json_encode(['id', 'name', 'order_num'])]);

Example response

[{"id":"1042","name":"Trade","order_num":"2"}]

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.

No rows returns []; a failed database read can return false. Supplied valid fields do not automatically include id.

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.
falseDatabase query fails; there is no endpoint-specific validation error for an empty/malformed projection.

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 WHERE, ORDER BY or LIMIT is added: name, IDs, search, start and length are ignored. Clients must sort by order_num themselves if needed.
  • No priceBands feature check or role guard beyond login. There is no active/archive or soft-delete column on price_bands.
  • 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

Open Customer Edit and the Price Band selector, the customer list Price Band filter, or Stock Edit’s price-band pricing area. Filter PriceBands_list; callers choose the raw fields needed for labels and pricing.

CRM2

No direct CRM2 caller was found; mapped widgets load PriceBand_getRequestedDetails, and cached pricing objects use PriceBands_getById.

Related endpoints