Change the recurrence customer or asset

When to use this endpoint

Use the recurring-jobs customer/asset picker. update=1 changes existing cached jobs immediately, unlike the reset-based user/form controls.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Tenant context is required. The Job edit-restriction bit 128 applies, with the existing client-administrator exception.

IDs resolve inside the authenticated tenant. There is no additional department-visibility or recurrence-ownership filter.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Positive recurrence ID in canonical integer form; not a job ID. The record must exist.
`cid`	Integer string	Yes	Positive active customer/asset ID; not the tenant ID.
`ctype`	Integer string	Yes	Exactly 0 customer or 1 asset.
`update`	Integer flag	Yes	Exactly 0 changes future-generation configuration only; 1 also applies the target through Job_setCustomer to active cached children.

Example request

$result = FM_api('JobRecurrence_setCustomer', ['id'=>'1042', 'cid'=>'1088', 'ctype'=>'0', 'update'=>'0']);

Example response

{"ok":1}

A post-save follow-up failure adds saved=1 and warning/warnings without undoing the settings. Read the warning and reload affected objects rather than blindly replaying the operation.

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 missing, invalid or not positive.
`{"error":"job recurrence 1042 does not exist"}`	No matching recurrence; numeric ID varies.
`{"error":"No permission to edit"}`	The Job edit restriction applies and the caller is not a client administrator.
`{"error":"Unable to save job delivery changes"}`	The checked local transaction failed; settings/history are rolled back.
`{"error":"Invalid job customer or asset"}`	The selected target is missing or deleted.
`{"error":"This user does not have access to certain CRM features. Check user permissions."}`	Existing-job update would affect linked billing without finance access.
`{"error":"Invalid saved recurrence metadata"}`	The saved metadata cannot be decoded as an array/object; it is not silently erased.
`{"error":"missing or invalid parameter: cid"}`	The cid value is missing or fails the documented integer/range requirement.
`{"error":"missing or invalid parameter: ctype"}`	The ctype value is missing or fails the documented integer/range requirement.
`{"error":"missing or invalid parameter: update"}`	The update value is missing or fails the documented integer/range requirement.

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

Behaviour and edge cases

Validates the selected nondeleted target before saving. Stores customer columns plus server-owned meta.target_override so future generation honors an explicit edit.
update=0 leaves every existing job untouched. Unmarked legacy sequences retain example-job target inheritance.
update=1 safely normalizes cached IDs and preflights finance access for active children with linked invoices before any recurrence/child save.
After committing the recurrence, updates active cached children through canonical Job_setCustomer, including its snapshots, parent cache, outsourcing and linked-invoice behavior. Completed active children can be included; deleted children are excluded.
Child operations are not batch-atomic. A later error returns saved warnings plus child_error, failedId and updatedIds for the processed prefix; reconcile these before retrying.

Side effects

The existing recurrence is locked and changed settings, edit timestamp/operation marker and history are committed together in a checked local transaction. Failed local persistence rolls back; an unchanged value normally returns ok without a new local write.
Cleanup, child-target changes and global scheduler/reminder reconciliation run after the local save. A failed follow-up preserves committed settings and returns ok=1, saved=1, warning/warnings. Inspect current state and any partial progress before retrying; tenant and global effects are not distributed-atomic.

See it in Fieldmotion

CRM1

Open Jobs → Recurring Jobs and edit the customer/asset cell. The dialog's update-existing choice is sent as update.

CRM2

In the recurring-jobs module, edit Customer and choose whether to change existing jobs. Filter for JobRecurrence_setCustomer; the picker sends cid, ctype and update.

Related endpoints

JobRecurrence_get reloads the stored settings after an edit.