Tax Rate

A TaxRate represents a named, workspace-scoped tax definition used to compute fiscal obligations on invoice line items and accounting postings. Each rate carries a percentage, a tax type classification (VAT, GST, SALES_TAX, EXCISE, WITHHOLDING, or EXEMPT), an optional country scope for multi-jurisdiction workspaces, and optional links to two LedgerAccount relations for collected (output) and deductible (input) tax accounting. TaxRates are referenced by InvoiceItem (via applied_tax_rate_pk), WorkspacePostingMapping, and JournalEntryLine, making them the central lookup table for the double-entry accounting layer.

API operations

Data model

Attributes

Relationships

System-computed

• tax_rate_id is generated via gen_random_uuid() as the PostgreSQL column default on insert; the MikroORM entity also calls randomUUID() as a JS-side default, meaning the value is always set before any database round-trip.
• created_at is set once on insert via the MikroORM @Property onCreate lifecycle hook (new Date()). It is never overwritten. The DB column is TIMESTAMPTZ NOT NULL DEFAULT now().
• updated_at is set on insert via onCreate and refreshed on every subsequent write via the onUpdate lifecycle hook. The DB column is TIMESTAMPTZ NOT NULL DEFAULT now(), so it is always present and never null.
• deleted_at is null for active records. Setting it to a non-null timestamp constitutes a soft delete. No hard-delete path exists for this entity — historical invoice lines and journal entries reference tax_rate_pk and must remain linkable.
• The table-level @Unique({ properties: ['workspace', 'name'] }) decorator maps to a full (non-partial) UNIQUE(workspace_pk, name) constraint in the migration. Unlike the ledger_accounts precedent which uses a partial index (WHERE deleted_at IS NULL), tax_rates uses a full unique constraint. Soft-deleting and then re-creating a rate with the same name will violate this constraint; a follow-up migration adding a partial index and dropping the full constraint is recommended.
• is_default has no database-enforced single-default-per-workspace constraint. Application-layer logic in the service must guarantee at most one default per tax_type (or globally) per workspace before persisting.
• rate is stored as DECIMAL(5,2) and surfaced as a string in the API to avoid floating-point rounding errors in JSON serialisation. Callers must treat it as a fixed-precision decimal string.
• effective_from and effective_to are stored as PostgreSQL DATE (date-only, no time component). The application layer is responsible for filtering available rates against a document's issue date when selecting the applicable rate.
• Downstream consumers that hold a hard FK to tax_rates include: core_api.invoice_items (applied_tax_rate_pk), core_api.workspace_posting_mappings (tax_rate_pk), and core_api.journal_entry_lines (tax_rate_ref_pk). Soft-deleting a tax_rate does not cascade to these references — historical records continue to point to the soft-deleted row.

Example

{
  "data": {
    "type": "tax_rate",
    "id": "d4e7a3c2-81f5-4b2e-9d6a-1c0f3e8b5a47",
    "attributes": {
      "tax_rate_id": "d4e7a3c2-81f5-4b2e-9d6a-1c0f3e8b5a47",
      "name": "TVA 20%",
      "rate": "20.00",
      "tax_type": "VAT",
      "country": "FR",
      "is_default": true,
      "is_active": true,
      "effective_from": "2024-01-01",
      "effective_to": null,
      "created_at": "2024-01-15T09:30:00.000Z",
      "updated_at": "2024-03-10T14:22:00.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
      },
      "collected_account": {
        "data": { "type": "ledger_account", "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210" }
      },
      "deductible_account": {
        "data": { "type": "ledger_account", "id": "1a2b3c4d-5e6f-7890-1234-abcdef567890" }
      }
    }
  }
}