Fieldmotion API Getting started

Customers

Update customer metadata

POST /a/Customer_updateMeta

Set one arbitrary top-level key in a customer’s legacy metadata JSON object.

When to use this endpoint

Use Customer_updateMeta only for established metadata keys used by the CRM, such as accounting email, additional email, or discount.

Prefer a named setter or Customer_updateData when the key has a mapped contract and needs validation, audit history, or notifications.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesCustomer ID.
metaStringYesTop-level metadata property name. It is trimmed and must be nonblank. No allow-list is applied.
valAny JSON-encodable valueYesValue assigned to the property. Blank strings, zero, arrays, and objects are accepted when the request transport can represent them.

Example request

$result = FM_api('Customer_updateMeta', [
	'id' => '1042',
	'meta' => 'discount',
	'val' => '10',
]);

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"}id is absent or not positive.
{"error":"missing or invalid parameter: meta"}meta is absent or blank after trimming.
{"error":"missing or invalid parameter: val"}The val key is absent; an explicitly blank value is allowed.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Existing valid metadata is decoded, the one key is replaced or added, and the whole object is encoded again. Missing, empty, or invalid metadata starts as an empty object and can discard malformed prior text.
  • The update does not require deleted=0, so it can change a soft-deleted customer.
  • The endpoint updates last_edited and edited_uuid but does not validate the meaning or type of val.
  • There is no pagination.

Side effects

  • Invalidates the customer cache and fires the Customer_edit event even when the update matched no row.
  • Does not write customer change history, the general activity log, mention notices, or customer update notifications.

See it in Fieldmotion

CRM1

Customer quick-edit and invoice views use this endpoint for accounting email, additional email, discount, and invoice-related metadata.

CRM2

The Customers page uses it for established quick-edit metadata fields; filter Network requests for Customer_updateMeta.

Related endpoints