Create a price band with mapped fields

When to use this endpoint

Use mapped creation with a required name and optional initial order, pricing mode or multiplier. The created band is timestamped and audited; assigning it to customers remains a separate operation.

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
`name`	String	Required on creation; optional on update	Trimmed nonblank name, at most 64 bytes. Duplicate names are accepted; mapped calls accept "0" while legacy new/setName reject it. Omitted update names are preserved.
`orderNum / isRelative`	Integer-compatible scalars	No	Integer-coerced. Creation defaults to 0; omission on updates preserves values. Negative order and modes other than 0/1 are not prohibited; other modes fall back to base price in Stocks_getPrice.
`relativeMultiple`	Finite numeric scalar	No	Numeric text/number is float-coerced; nonnumeric, blank and nonfinite supplied values are rejected. No sign/range restriction. Creation defaults to 1; omission on update preserves it. 0.9 means 90% of base price.
`cDate`	Integer-compatible Unix seconds	No	Optional caller-supplied creation timestamp. Creation defaults to current server Unix time; supplied values are integer-coerced and mapped updates can change it.
`lastEdited`	Ignored legacy input	No	Server-owned edit timestamp. Supplied values cannot suppress or backdate the edit; changed rows use current server Unix time. No-op edits preserve the existing timestamp.

Example request

$result = FM_api('PriceBand_createData', ['name'=>'Trade', 'orderNum'=>'2', 'isRelative'=>'1', 'relativeMultiple'=>'0.9']);

Example response

{"ok":1,"id":1042}

Returns numeric ok and the insert ID, without a full row. Reread mapped details to confirm storage.

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: name"}`	Name omitted, null, blank, nonstring or whitespace-only.
`{"error":"name too long. max length 64"}`	Trimmed name exceeds 64 bytes.
`{"error":"missing or invalid parameter: relativeMultiple"}`	A supplied multiplier is nonnumeric or nonfinite.
`{"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

Mapped fields are id, name, orderNum, isRelative, relativeMultiple, cDate and lastEdited; the latter five map to order_num, is_relative, relative_multiple, cdate and last_edited.
Name is required, trimmed and validated before insertion. Unknown keys, supplied id, noRecord and noRecordCustom are ignored; null optional fields count as omitted.
Creation defaults order_num=0, is_relative=0 and relative_multiple=1. cDate defaults to current Unix seconds; lastEdited is always stamped by the server.
No finance-feature or extra role guard; duplicate names remain allowed. Numeric integer fields use integer coercion; multiplier input must be finite numeric.
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

Inserts one tenant price_bands row, invalidates the cache and writes checked field history in the same transaction. No customer assignment, stock override, configured event, 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

Open Settings → Finance → Price Bands and choose Add. The display widget synthesizes PriceBand_createData. The UI requires a name and disables initial order/mode/multiplier inputs; these restrictions are not enforced by this handler.

Related endpoints

PriceBand_new provides validated legacy creation with server timestamps.
PriceBand_getRequestedDetails reads the created mapped row.