Create a price band with legacy defaults

When to use this endpoint

Use this legacy creation route when a named band with timestamped defaults is needed. Assign the returned ID to customers separately; creating a band does not change prices.

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	Yes	Trimmed, nonempty and at most 64 bytes, not 64 Unicode characters. The string "0" fails the truthiness check. Duplicate names are accepted.

Example request

$result = FM_api('PriceBand_new', ['name'=>'Trade']);

Example response

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

The ID is explicitly converted to an integer.

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"}`	Omitted, blank after trimming, or the literal string "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

Name validation precedes the login guard. Whitespace around an accepted name is removed.
Uses schema defaults order_num=0, is_relative=0 and relative_multiple=1; cdate and last_edited are set to the current server Unix time.
No uniqueness or finance-feature guard is enforced. Insertion and required field history are checked in one tenant transaction; errors do not return an ID.
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 a tenant price_bands row, stamps server timestamps, invalidates its cache and records checked field history. No customer assignment, stock override, configured event, notification or external request.

See it in Fieldmotion

CRM1

Open Settings → Finance → Price Bands, choose Add and enter a name. Filter Network requests for PriceBand_new. Stock/customer imports also create missing named bands through this route.

CRM2

Stock/customer import workflows create missing named price bands through PriceBand_new; filter that request during the import. The finance Add dialog instead uses PriceBand_createData.

Related endpoints

PriceBand_createData accepts initial mapped fields and a required validated name.
PriceBand_get reads one raw row, including integer timestamps.
PriceBand_getRequestedDetails reads mapped fields for one or several IDs.