Parties (customers and suppliers)
Parties (customers and suppliers)
A party is the counterparty you transact with. For bookkeeping, customers and suppliers are the same concept: the party attached to an invoice, a bank transaction, and sometimes directly to a posting for review and audit navigation.
Party master data reduces duplicates, improves matching, and makes reports and evidence trails easier to read. Even when you keep separate “clients” and “purchase companies” in operational screens, bookkeeping benefits from treating them as one master concept with shared identifiers and defaults.
Ownership
Owner: bus entities. This module is responsible for implementing write operations for this object and is the only module that should directly change the canonical datasets for it.
In the current CLI surface, bus entities add records the stable entity identifier and display name. Other party fields that exist in the workspace schema (such as business identifiers, VAT numbers, country codes, payment identifiers, and default bookkeeping fields) are maintained by editing entities.csv directly and validating with bus validate, so field editability remains explicit and script-friendly.
Secondary read-only use cases are provided by these modules when they consume this object for validation, matching, posting, or reporting:
bus invoices references parties on invoices for receivables and payables. bus bank uses party data for matching and counterparty display, and bus reconcile matches cash movement to invoices and parties.
Actions
Register a party creates or imports counterparties so invoices and matching can link deterministically. Deduplicate parties merges duplicates so reporting and audit trails point to one legal entity. Set party bookkeeping defaults maintains default accounts, VAT handling, and payment identifiers used in matching and prefill.
Properties
Core identity fields are party_name, business_id, vat_number, and country_code.
Default bookkeeping fields are default_sales_account_id, default_expense_account_id, default_vat_treatment, and payment_identifiers.
Party defaults and identifiers support deterministic VAT treatment selection and validation, especially when cross-border rules and exemptions apply.
Relations
A party belongs to the workspace’s accounting entity. Scope is derived from the workspace root directory, and the same party record can be referenced by multiple bookkeeping objects over time.
Sales invoices reference a customer party via client_id. Purchase invoices reference a supplier party via purchase_company_id. Bank transactions can reference parties on either side using client_id and purchase_company_id.
Employees reference a party record via entity_id so payroll can keep identity and payment data consistent with the party master. Loans reference a party via counterparty_id.