Fieldmotion API Getting started

Invoices

Enable credit notes

POST /a/CreditNote_enable

Permanently enable the tenant credit-note feature and migrate active legacy invoices stored with Credit Note status.

When to use this endpoint

Use this once from Invoice Settings after reviewing the one-way migration. It is not an ordinary settings toggle and there is no disable counterpart.

Authentication and permissions

The request must authenticate as the tenant’s client administrator; API-key authentication is accepted only when it resolves to that administrator context.

This route does not require Credit Notes to be already enabled and does not apply the legacy finance-access bit check used by the other credit-note routes.

Parameters

ParameterTypeRequiredDescription
confirmationExact stringYesMust exactly equal I am sure, including case and spaces.

Example request

$result = FM_api('CreditNote_enable', ['confirmation' => 'I am sure']);

Example response

{
  "ok": 1,
  "migration": {
    "ok": 1,
    "created": 2,
    "already": 0,
    "soft_deleted": 2
  }
}

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":"only client admins can enable Credit Notes"}The authenticated user is not the tenant client administrator.
{"error":"Credit Notes migration is already running"}Another migration lock is newer than 15 minutes.
{"error":"Could not start Credit Note change. Please retry."}The database transaction could not begin.
{"error":"Credit Note change could not be saved. Please reload before retrying."}A database write or commit failed; the transaction is rolled back. For enablement, earlier completed invoice migrations remain committed.

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

Behaviour and edge cases

  • If already enabled, returns {"ok":1,"warning":"Credit Notes are already enabled"} without another migration.
  • Every active invoice with status 4 becomes an Issued credit note. The migrated note records meta.legacy_invoice_id, retains document/customer/row/accounting fields, copies direct and ancillary job relationships into relation type 14, and moves api_syncs.object_type=credit mappings to the new ID.
  • The old invoice is soft-deleted. A retry finds previously migrated notes by scanning their metadata and avoids creating a second note.

Side effects

  • Writes the migration lock setting, creates credit notes and snapshots, copies relationships, retargets accounting sync mappings, soft-deletes legacy invoices, enables accounting_credit_notes, and logs the migration counts.
  • Every migrated legacy invoice receives a tenant deletion-stream record. An audit failure prevents that invoice’s migration from committing.

See it in Fieldmotion

CRM1

No CRM1 enable control was found.

CRM2

Open Invoice Settings and choose Enable Credit Notes. The UI requires the same typed confirmation and reloads after success.

Related endpoints