SIGNALS Docs

Account credit control

How tenant-wide credit exposure, headroom, on-stop and cash accounts, credit overrides, rollout modes, collections annotations and reconciliation work for accounts.

Overview

This is a reference page for Accounts. It explains how commercial credit decisions are made and evidenced. For the repair commands referenced below, see Account data repair.

Commercial commands use the recorded decision from AccountCreditDecisionService.

Cached headroom, account registers, briefing verdicts, API read responses, and viewer-scoped warehouse details are presentation data. Never use those values, a preceding decision, or a client-supplied credit result as authorization for a new action. Each new commercial command rechecks current tenant-wide exposure and policy at the action boundary; a replay applies only to its original command identity. Credit visibility does not grant mutation or override permission.

Credit decisions are tenant-wide and are not limited by the acting user's warehouse access. The authoritative exposure is:

open receivables + remaining active-order commitments + active non-materialised reservations

Warehouse explanations use the same contributors as that total, including live incremental reservations in reservation-only warehouses. Reservations without an available rental warehouse appear in an unassigned bucket. Incomplete reservation money withholds that bucket's reservation and total amounts. The presentation keeps the tenant-wide total but shows only warehouse details the viewer may access; the unassigned bucket is shown only to unrestricted viewers. Account and document permissions are checked before exposure queries, and foreign or unavailable tenant contexts are refused before alias resolution.

The service records every decision as immutable evidence. It locks the credit account before the rental, retries bounded deadlocks, and uses a unique source command for database idempotency. Quote-to-order conversion, customer reassignment, exposure-increasing price or quantity changes, and physical dispatch recheck policy inside the same transaction as the commercial change.

  • A null credit limit means unlimited. A zero limit is a real zero limit.
  • On stop blocks new commitment and dispatch, but does not block invoicing, return, cancellation, payment, credit, refund, or collection work that reduces or bills existing exposure.
  • Cash account requires cleared settlement for the rental before commitment or dispatch.
  • Missing required base-currency or stored-rate evidence prevents ordinary approval. Foreign minor units are never compared as if they were base currency. An explicitly valid, audited override can permit the currency refusal under the commercial policy; it does not repair missing evidence.
  • Overrides require accounts.credit.override, a reason code and explanation, an account and boundary scope, and any supplied rental and amount ceiling. Tenant policy can require a different second approver. Omitting the expiry argument uses the default 60 minutes; explicitly passing null disables expiry. Do not assume every override expires. A policy refusal returns override_required with a specific reason code; this result is not approval.
  • accounts.credit.rollout_mode supports report, warn, and enforce. Report and warning modes may permit ordinary policy breaches with a recorded warning. Enforcement mode blocks them unless a valid override applies. Report and warn modes never downgrade currency, pricing or exposure-pause refusals; separately valid overrides follow the boundary below.

The credit register and account page use AccountCreditPresentation to show tenant-wide exposure, overdue amounts, active reservations, on-stop and cash flags, completeness, UTC generation time and credit version. Warehouse contribution rows contain receivables and remaining order commitments; reservations are listed separately, including rental-less reservations for unrestricted viewers. Restricted viewers see only accessible warehouse and rental details, while the global exposure and headroom still include every warehouse. The raw financial snapshot returns zero for disputed_minor, but presentation returns null with disputed_complete: false and disputed_incomplete_reason: disputes_not_tracked; the page explicitly shows that disputes are unavailable.

Supported credit contracts

The read-only Accounts command contract includes credit_capabilities, schema version 1. REST and the curated get-account-command-contract MCP tool return the same catalogue: commitment, dispatch, repricing and reassignment boundaries; recorded result names; six published policy refusal codes; and the separate internal identity-denial classification. The catalogue describes installed contracts and contains no account values or actor-specific verdict. There is no standalone public credit-decision endpoint.

Rental action preflight attaches the appropriate contract to conversion and dispatch; its ordinary lifecycle allowed flag is not a credit decision. Rental-conversion approvals expose the commitment contract, and workflow override configuration publishes the same reason guidance. The credit-utilisation dashboard includes the static catalogue, while credit-decision reporting keeps its existing permission and recorded reason field. Rental documents can use credit_capabilities.schema_version, evaluation, grants_authority and reason_codes; these fields describe supported contracts, including on money-free dispatch documents, and never disclose a customer's exposure, private reason or recorded decision.

New commercial credit decisions continue to use AccountCreditDecisionService. Catalogue reads, cached headlines, approval, document generation and a preceding allowed result do not authorize new exposure. Historical or unknown recorded reason codes are kept as recorded; publication does not rewrite them or turn missing money into an approval.

Credit inputs, overrides and reconciliation

The rental-to-order workflow accepts an optional credit_override_id UUID and passes it to the same conversion and credit commands used by direct rental mutations. Grant the override through the authorised account command first. A selected override starts a distinct command intent; retrying that intent preserves its original decision, including a refusal. The workflow still requires delegated rental-edit capability and current warehouse access; an unrelated, expired or incorrectly scoped grant cannot bypass credit checks.

The executable exposure equation uses the liable customer's standard posting invoices: gross subtotal plus tax, less effective applied/issued credits and net allocated cash (with the finance equation's net write-off adjustments). Draft or void credit notes have no financial effect. Each active order contributes max(0, frozen gross order total - issued standard posting invoice gross total); tax is included in both terms. A payment or effective credit reduces receivables without reopening already invoiced commitment. Cancellation can leave refundable overpayment, which is not a positive receivable. Complete or cancelled orders, draft/void/non-posting invoices, deposits and pro-formas do not create additional exposure; non-posting deposit/pro-forma documents also do not reduce an order commitment.

Rental subtotal is the net calculator headline. Credit commitments and boundary reservations add separately validated frozen net and tax base amounts, with checked integer addition. Missing tax conversion evidence withholds the gross credit amount just as missing net conversion evidence does; no live conversion repairs either component.

Unallocated payments, unapplied settlements and draft credit notes do not reduce invoice exposure until explicit invoice allocation or credit application changes its outstanding balance. This preserves unapplied funds for their eventual allocation or refund without spending them against a second liability. Payments already attached to prior non-posting deposits do not reduce standard receivables or remaining order commitment. New direct payments to non-posting documents are refused; cash is recorded as an unapplied settlement for explicit allocation.

Only active, non-expired reservations whose rentals are not already represented by active orders contribute incremental exposure; rental-less active reservations remain included. Owner, contact and venue links provide CRM history without making that account the liable customer. Merged liable account ids contribute to their canonical customer's exposure. Disputed debt remains liable receivables until a real financial adjustment changes it: free-text dispute annotations do not discount it, and the raw zero disputed field is an unsupported metric, not an assertion of no disputes. A zero or null limit changes the policy decision rather than the exposure equation; an exact-limit zero increment remains admissible. Missing foreign conversion evidence makes the affected component and total unknown; frozen valid base evidence supplies base minor units without live rate substitution. An integer overflow also withholds the total with an explicit incompleteness reason.

Headroom is credit limit - exposure; presentation may clamp it with max(0, credit limit - exposure). A null limit or incomplete exposure has no numeric headroom. Base-currency amounts must come from valid stored money evidence, not today's exchange rate or a sum of foreign minor units. An incomplete snapshot has null exposure and explicit incomplete_reasons.

Active reservations count only while expiry is null or in the future, and only before their rental is already represented by an active order. This prevents double counting materialised commitments. Non-base reservation currency or negative amounts make the snapshot incomplete. Ordinary release locks the credit account and reservation, changes active status to released, clears expiry and advances credit version; repeating release is a no-op and preserves decision history.

The current decision checks rental identity eligibility before credit overrides for commitment, dispatch or positive increments: rental_identity_ineligible is a denial. Credit reason priority is pause, pricing evidence, currency/settlement completeness, on-stop, cash shortfall, then limit. Codes are credit_new_exposure_paused, credit_pricing_incomplete, credit_currency_incomplete, credit_account_on_stop, credit_cash_settlement_required and credit_limit_exceeded. Cash requirements use cleared settlement, not a promised payment. A selected credit_pricing_incomplete reason excludes overrides; valid overrides are checked before rollout warnings for other selected credit reasons.

Override availability checks active status, account, optional rental, scope (all, commitment, dispatch, reprice or reassign), amount ceiling and non-null expiry. Supplied expiry ranges from one minute to seven days. The recorded override currency is not checked by availability. Explicit-null expiry and unchecked currency are current limitations. A required second approver must differ from the requester; credit visibility alone grants neither decision nor override authority.

Overdue ageing uses open invoice outstanding amounts with a non-null due_at prior than the current time, converted through the same stored base-money evidence. Inspect source invoices and due dates before interpreting ageing; no overdue date is invented for an undated invoice and the zero disputed field is not evidence that no dispute exists.

For reconciliation, compare current invoice outstanding, remaining active-order commitments and active reservation rows with the snapshot's source contributions and incomplete reasons. Preserve immutable decisions and original refusals. Repair missing money or accepted-pricing evidence through its owning domain; do not replace it with a cached display, override or today's rate.

Run the read-only health report first, then use signals:accounts:repair expired-reservations with explicit --account IDs, --expected-manifest-version, a bounded --batch (1–100) and --dry-run. Dry-run preserves operational rows but writes an immutable evidence receipt. Review before/after counts and source rows before an authorised --repair with a reason and confirmation. --resume names the preceding receipt and must match operation, mode, manifest digest/version and the exact deduplicated account list; an already complete receipt is a no-op. A dry-run receipt cannot skip a later live repair: start that live run without --resume. Reservation repair releases active expired rows, rows with null rental ID and rows linked to terminal lost/expired quotes or complete/cancelled orders. Its bulk repair is distinct from the ordinary versioned release command; a repair receipt alone does not certify whole-account reconciliation. Never delete decision history to reconcile totals.

Global identity, warehouse operations and sensitive fields

An account is one tenant identity, not a separate customer balance in each warehouse. Account::accessibleInUserWarehouses limits account discovery to permitted warehouse assignments while accounts with no warehouse assignments remain globally visible to the tenant's authorised viewers. Rental, invoice, project and document details still require their source-domain abilities and operational warehouse scope.

Authoritative credit is tenant-wide because receivables, active-order commitments and reservations across warehouses consume the same credit limit. AccountCreditExposure removes viewer warehouse scope for that total while retaining tenant and money-validity boundaries. Viewer redaction filters warehouse contribution and reservation details; it must not subtract inaccessible warehouses from the authoritative exposure or grant permission to book work.

Sensitive field class Current boundary
Identity and subtype Name, type and lifecycle identify the shared account; mutation uses the applicable account command and ability.
Contact PII Addresses, email addresses and phone numbers are personal data even when attached to a Company or Venue.
Commercial and legal Tax identifiers, payment terms, prices and retained invoice provenance need their own access and retention controls.
Credit evidence Exposure, headroom, reservations and decision history require credit and applicable source-domain permissions.
Operational and audit details Warehouse-specific documents and work require their domain access; credit limit history is removed when audit access is absent.

These classes describe sensitivity, not a universal field-redaction guarantee. AccountData::fromModel serialises loaded addresses, emails, phones and the account's typed profile without checking accounts.contact-pii.view or accounts.commercial.view itself, so a permission-table entry does not mean every DTO, page, API, export or cache enforces that ability. Check the actual reader before sharing sensitive fields; comprehensive field-level redaction is not yet available.

The installed register requires account visibility and the applicable invoice/rental/credit abilities; its creditOnly response returns null limit, headroom and completeness when any of those three abilities is absent. The register and account credit panel consume AccountCreditPresentation: without any of the three source/credit abilities its service response is exactly {authorized: false}, and without account visibility it refuses. Authorized reads bind canonical account generation and current authorization before returning. The service preserves signed headroom; the register clamps available headroom to zero. Register cache schema 17 prevents reuse of the preceding credit shape.

Cached register results bind viewer authorisation and warehouse scope, and refresh checks that authorisation has not changed. These presentation controls do not replace fresh commercial-command permission, exposure and override checks, and do not redact unrelated contact or legal readers.

Collections annotations and policy history

The account collections API provides protected, typed annotations through GET and POST /api/v1/accounts/{account}/collections. A note contains a body; a review_date contains due_at as a UTC calendar date; a payment_promise contains a positive integer amount_minor, an explicit known currency_code and due_at. New due dates must be today or later. Reads include the actor, creation time and account version recorded for each entry. An optional expected_version uses the released account precondition policy and refuses stale values under the account lock without changing the account version. Promises do not record settlement or change outstanding debt, exposure, cash requirements, limits, reservations or credit decisions. No currency conversion is performed.

Every operation requires current accounts.view. Notes and review dates additionally require accounts.contact-pii.view; promises and policy history require accounts.credit.view. Mutation requires accounts.edit plus accounts.contact-pii.edit for PII annotations or accounts.credit.decide for promises. Permission checks use a freshly loaded active actor on each call; denied categories return no values and do not query their annotation table. Reads return the latest fifty entries per category across the canonical account and its aliases, with protected note text hex-escaped in JSON. Writes refuse non-mutable or privacy-restricted accounts and unbound cloud contexts.

Successful UpdateAccount changes to credit limit, cash/on-stop flags and invoice terms append the actual original/new fields with the resulting aggregate version in the same transaction. No-op and unrelated identity changes append no policy history; rollback removes the history with the update. This is forward history from the installed producer, not a reconstruction of missing historical changes. Clients cannot submit a policy-change entry directly.

accounts.collection_notes uses the existing mutable customer-PII policy (case_completion); finance.collection_records uses the existing legal-record policy (source_record_retention_schedule). No new retention duration is introduced. Active legal holds refuse destructive dispositions. Approved PII redaction clears the subject's note bodies and review dates idempotently; author-only references are cleared without erasing another subject's content. Financial records retain their typed evidence under legal-obligation restrictions and record the retained exception. Note bodies and financial payloads are encrypted at rest. Bodies, review dates and financial payloads are hidden from ordinary model serialization; authorized subject export remains private and scoped. These repositories participate in the account reference manifest and privacy registry.