Set invoice-email suppression

When to use this endpoint

Use Customer_setDoNotEmailInvoices to store the invoice-email suppression choice after a user decides that invoices must not be emailed to this customer.

The flag is consumed by invoice-send workflows. It does not validate or change the customer email address.

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

Parameter	Type	Required	Description
`id`	Integer string	Yes	Customer to update; it must convert to a positive integer.
`val`	Integer-like value	Yes	Stored under `meta.do_not_email_invoices` after `intval` conversion. Production callers use `1` to suppress and `0` to allow; the handler accepts other integers.

Example request

$result = FM_api('Customer_setDoNotEmailInvoices', [
	'id' => '1088',
	'val' => '1',
]);

Example response

{
  "ok": 1
}

A loosely equal existing flag returns {"ok":1,"warning":"no change made"}.

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: id"}`	`id` is absent or invalid.
`{"error":"missing parameter: val"}`	`val` is omitted.
`{"error":"customer does not exist: 1088"}`	No row matches the customer ID; the numeric ID is appended to the message.

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

Behaviour and edge cases

The customer lookup does not filter inactive or soft-deleted rows.
Invalid or non-array customer metadata is replaced with a new map containing this flag.
The handler does not constrain the converted integer to zero or one. Invoice callers treat the metadata value as a suppression flag.
This is a single-record mutation; it provides no list filtering or pagination.

Side effects

The write replaces the encoded meta value, updates last_edited, and invalidates the customer cache. It does not set edited_uuid.
The handler writes a customer audit event and fires Customer_edit; it does not add a customer_changes row.

See it in Fieldmotion

CRM1

When an invoice-email workflow encounters an unsuitable customer email, CRM1 can store the user’s decision through Customer_setDoNotEmailInvoices. Filter Network requests by the function name.

CRM2

The QuickBooks connector in CRM2 calls this endpoint for the same invoice-email preference. Normal customer editing uses the broader layout update contract.

Related endpoints

Customer_getMeta retrieves the raw metadata containing this flag.
Customer_setEmail changes the customer email address independently.