> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkspaceAccountingSettings

> WorkspaceAccountingSettings stores the per-workspace accounting configuration that governs how Well processes invoices, journal entries, and reporting for a giv

WorkspaceAccountingSettings stores the per-workspace accounting configuration that governs how Well processes invoices, journal entries, and reporting for a given tenant. Each workspace has at most one settings row (enforced by a UNIQUE constraint on `workspace_pk`), making this effectively a 1-to-1 extension of the Workspace entity. The row is created by the onboarding/setup flow (seed or `WorkspaceService`) and subsequently updated either by the user via `PUT /v1/workspaces/:id/accounting-settings` or automatically by `WorkspaceSelfIdentityService` when invoice-extraction consensus is reached. It anchors the workspace's fiscal identity (base currency, country, accounting framework, business registration details) and configures two LedgerAccount defaults used by the journal-entry posting engine.

| Naming                          | Value                               |
| ------------------------------- | ----------------------------------- |
| Object                          | WorkspaceAccountingSettings         |
| Resource type (JSON:API `type`) | `workspace_accounting_settings`     |
| Collection / records root       | — <sub>(not a records root)</sub>   |
| REST base                       | `/v1/workspace-accounting-settings` |
| Entity class                    | `WorkspaceAccountingSettings`       |

<Note>
  **Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
</Note>

## API operations

| Operation | Method & path                                   | Status     |
| --------- | ----------------------------------------------- | ---------- |
| List      | `GET /v1/workspace-accounting-settings`         | 🟡 Planned |
| Retrieve  | `GET /v1/workspace-accounting-settings/{id}`    | 🟡 Planned |
| Create    | `POST /v1/workspace-accounting-settings`        | 🟡 Planned |
| Update    | `PATCH /v1/workspace-accounting-settings/{id}`  | 🟡 Planned |
| Delete    | `DELETE /v1/workspace-accounting-settings/{id}` | 🟡 Planned |

## Data model

### Attributes

| Field                               | Type                                     | Required | Constraints                                                                                                                                                                                | Allowed values                                                                         | Description                                                                                                                                                                                                                                                |
| ----------------------------------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspace\_accounting\_settings\_id | string (UUID)                            | ✅ Yes    | unique; default gen\_random\_uuid()                                                                                                                                                        | any valid UUID v4                                                                      | Public API identifier for this settings row.                                                                                                                                                                                                               |
| base\_currency                      | string (CurrencyCodeEnum) \| null        | ⚪ No     | nativeEnumName: currency\_code\_enum; nullable                                                                                                                                             | ISO 4217 codes, e.g. EUR, USD, GBP (full set in CurrencyCodeEnum from @wellapp/shared) | The workspace's base accounting currency. Drives exchange-rate selection and multi-currency invoice normalization.                                                                                                                                         |
| country                             | string (CountryCodeEnum) \| null         | ⚪ No     | nativeEnumName: country\_code\_enum; nullable                                                                                                                                              | ISO 3166-1 alpha-2 codes, e.g. FR, DE, US (full set in CountryCodeEnum)                | Jurisdiction of the workspace's registered entity. Used for tax defaults and accounting-framework recommendations.                                                                                                                                         |
| accounting\_framework               | string (AccountingFrameworkEnum) \| null | ⚪ No     | nativeEnumName: accounting\_framework\_enum; nullable. Note: PostgreSQL enum also retains the deprecated value 'MAR' (cannot be dropped); any existing 'MAR' rows were migrated to 'IFRS'. | PCG \| IFRS \| US\_GAAP \| SKR                                                         | Chart-of-accounts framework in use. Determines which ledger account plan is available and how journal-entry drafts are structured.                                                                                                                         |
| fiscal\_year\_start\_month          | integer \| null                          | ⚪ No     | nullable; CHECK (fiscal\_year\_start\_month >= 1 AND fiscal\_year\_start\_month \<= 12) when not null                                                                                      | 1–12                                                                                   | Month number (1 = January) on which the workspace's fiscal year begins. Null means not yet configured.                                                                                                                                                     |
| tax\_id\_value                      | string \| null                           | ⚪ No     | length ≤ 50; nullable                                                                                                                                                                      | —                                                                                      | Workspace's tax registration number (e.g. VAT number, SIRET/SIREN, EIN). Extracted from invoices by WorkspaceSelfIdentityService via consensus.                                                                                                            |
| tax\_id\_type                       | string \| null                           | ⚪ No     | length ≤ 20; nullable                                                                                                                                                                      | —                                                                                      | Type label for tax\_id\_value (e.g. 'VAT', 'SIRET', 'EIN').                                                                                                                                                                                                |
| registered\_name                    | string \| null                           | ⚪ No     | length ≤ 255; nullable                                                                                                                                                                     | —                                                                                      | Full legal registered name of the workspace entity, as it appears on official documents.                                                                                                                                                                   |
| trade\_name                         | string \| null                           | ⚪ No     | length ≤ 100; nullable                                                                                                                                                                     | —                                                                                      | Operating / brand name of the workspace entity, if different from registered\_name.                                                                                                                                                                        |
| registered\_value                   | string \| null                           | ⚪ No     | length ≤ 100; nullable (widened from 50 in Migration20260427100000)                                                                                                                        | —                                                                                      | Secondary registration identifier (e.g. SIREN, RCS number) distinct from the tax\_id. Stores the plain numeric or alphanumeric value without a type prefix.                                                                                                |
| domain                              | string \| null                           | ⚪ No     | length ≤ 253; nullable                                                                                                                                                                     | —                                                                                      | Primary web domain of the workspace entity (RFC 1035 max 253 chars). Used for identity matching and enrichment.                                                                                                                                            |
| invoice\_status\_tolerance\_pct     | string (decimal 6,4)                     | ✅ Yes    | NOT NULL; DEFAULT 0.0100; CHECK (invoice\_status\_tolerance\_pct >= 0 AND invoice\_status\_tolerance\_pct \<= 1)                                                                           | 0.0000–1.0000 (inclusive)                                                              | Percentage-of-grand-total tolerance band for invoice payment\_status recomputation. The larger of (grand\_total × pct) and invoice\_status\_tolerance\_abs is used as the allowable rounding gap, then capped per InvoiceStatusRecomputeService plan §4.3. |
| invoice\_status\_tolerance\_abs     | string (decimal 12,2)                    | ✅ Yes    | NOT NULL; DEFAULT 0.50; CHECK (invoice\_status\_tolerance\_abs >= 0)                                                                                                                       | ≥ 0                                                                                    | Absolute monetary tolerance (in base\_currency) for invoice payment\_status recomputation. Used in conjunction with invoice\_status\_tolerance\_pct.                                                                                                       |
| created\_at                         | 🔒 system — Date                         | ✅ Yes    | set once on insert; never updated                                                                                                                                                          | —                                                                                      | Timestamp of row creation.                                                                                                                                                                                                                                 |
| updated\_at                         | 🔒 system — Date \| undefined            | ⚪ No     | set on insert and on every update via onUpdate hook                                                                                                                                        | —                                                                                      | Timestamp of last modification.                                                                                                                                                                                                                            |
| deleted\_at                         | Date \| null                             | ⚪ No     | nullable; soft-delete sentinel                                                                                                                                                             | —                                                                                      | Soft-delete timestamp. Non-null means the settings row has been logically deleted. All active queries must filter deleted\_at IS NULL.                                                                                                                     |

### Relationships

| Name                         | Type                         | Required | Description                                                                                                                                                                                                        |
| ---------------------------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| workspace                    | to-one (OneToOne owner side) | ✅ Yes    | The workspace this settings row belongs to. This entity owns the foreign key (workspace\_pk). The UNIQUE constraint on workspace\_pk enforces the 1-to-1 cardinality at the DB level.                              |
| account\_receivable\_default | to-one (ManyToOne)           | ⚪ No     | Default LedgerAccount used for the accounts-receivable line when the posting engine generates journal entries for outbound invoices. Nullable — if absent, the posting engine falls back to plan-defined defaults. |
| account\_payable\_default    | to-one (ManyToOne)           | ⚪ No     | Default LedgerAccount used for the accounts-payable line when the posting engine generates journal entries for inbound invoices. Nullable — if absent, the posting engine falls back to plan-defined defaults.     |

### System-computed

* workspace\_accounting\_settings\_id: generated via gen\_random\_uuid() at insert; client must not supply this value.
* created\_at: set by MikroORM onCreate hook at insert time; never overwritten.
* updated\_at: set by MikroORM onCreate hook at insert and by onUpdate hook on every subsequent flush.
* deleted\_at: written only by soft-delete logic; never set via the upsert API path.
* Row creation: WorkspaceService.setupWorkspace() creates the initial row via WorkspaceAccountingSettingsRepository.persist() during workspace onboarding. WorkspaceAccountingSettingsService.upsertByWorkspace() handles all subsequent writes (find-or-create semantics — it creates the row if absent).
* Identity field auto-population: WorkspaceSelfIdentityService applies an N=2 consensus rule over WorkspaceIdentityExtraction rows before committing values (registered\_name, tax\_id\_value, tax\_id\_type, registered\_value, domain, trade\_name, base\_currency, country, accounting\_framework) to this table automatically.
* accounting\_framework PostgreSQL enum retains the deprecated 'MAR' value (removed from application code; cannot be dropped via ALTER TYPE). Any pre-existing 'MAR' rows were migrated to 'IFRS' by Migration20260409200000.
* Tolerance defaults: invoice\_status\_tolerance\_pct defaults to 0.0100 (1%); invoice\_status\_tolerance\_abs defaults to 0.50. Both are application-layer defaults that align with InvoiceStatusRecomputeService plan §4.3 caps.

## Example

```json theme={null}
{
  "data": {
    "type": "workspace_accounting_settings",
    "id": "c3a7e291-11b4-4f8a-9f2c-847bde2a0e11",
    "attributes": {
      "base_currency": "EUR",
      "country": "FR",
      "accounting_framework": "PCG",
      "fiscal_year_start_month": 1,
      "tax_id_value": "FR42501234567",
      "tax_id_type": "VAT",
      "registered_name": "Acme SAS",
      "trade_name": "Acme",
      "registered_value": "501234567",
      "domain": "acme.com",
      "invoice_status_tolerance_pct": "0.0100",
      "invoice_status_tolerance_abs": "0.50",
      "created_at": "2026-01-15T09:22:00.000Z",
      "updated_at": "2026-04-03T14:10:55.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspaces", "id": "9f3b1c20-55ea-4a1b-b8f0-fe1234abcd99" }
      },
      "account_receivable_default": {
        "data": { "type": "ledger_accounts", "id": "aab10000-0000-0000-0000-000000000001" }
      },
      "account_payable_default": {
        "data": { "type": "ledger_accounts", "id": "aab10000-0000-0000-0000-000000000002" }
      }
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/WorkspaceAccountingSettings.ts` · domain: financial-graph · tier: Infrastructure</sub>