# Posting Workflows ## Contents - Hard accounting rules - Source-document extraction and visual confirmation - Resource-creation defaults - Customer invoicing - Recurring bookkeeping - Customer-facing document templates - Chart-of-accounts rules - Date rules - Prefer first-class workflows - Common posting patterns - Opening balances ## Hard Accounting Rules - use first-class business-document workflows before manual journals - use recurring templates for predictable repeats instead of cloning prior-period invoices, bills, or journals by hand - post from evidence, not guesses - before editing an existing draft journal or recurring journal template, read its full current detail and live update schema. Preserve original currencies, exchange rates, source and functional amounts, tax and dimension facts, and attachment and external-document links in the required replacement payload; do not assume a description-only update preserves omitted fields. If the desktop form cannot edit the record's currency or rate, use the supported agent/API update with those original facts, then read back and compare the result. Do not convert the record to the book currency merely to make the simplified form accept it - never net receivables, payables, taxes, or clearing balances against revenue or expense - do not overwrite posted history; use reversal, cancellation, credit-note, reopen, or the dedicated posted tax-code correction workflow - keep statutory tax separate from non-tax levies, remittances, tips, rebates, and similar document components; do not force those into tax codes or tax summaries - create one ledger account per real bank account, debit card, credit card, and loan - reconcile every bank and debit account to statements - tie every credit-card liability account to the card statement - do not use manual journals to create normal AR, AP, immediate cash-sale, or immediate cash-purchase or refund activity when invoice, sales receipt, customer refund, bill, expense, vendor refund, receipt, payment, or apply workflows exist - do not move dates only to make reconciliation easier - do not use opening balances to smuggle in current-period activity - treat void and reversal workflows as dated accounting events, not as silent deletion of historical activity - do not use `resources:batchDelete` to remove posted invoices, bills, sales receipts, customer refunds, receipts, expenses, vendor refunds, payments, payroll runs, inventory activity, or fixed-asset activity - permanently delete an employee only when the record was created by mistake and has no saved payroll setup, legal identity, payroll run, pay statement, vacation record, statutory record, accounting entry, or other retained history. Use `POST /v1/books/{book_id}/resources:batchDelete` with `resource: "employees"`, the confirmed employee IDs, Payroll module access, and the normal idempotency controls. Treat `DELETE_CONFLICT` as authoritative: never remove dependent payroll records to force deletion; edit the employee and set the status to inactive instead - permanently delete a pay schedule only when it was created by mistake and has never been assigned to an employee or referenced by payroll records. Use `POST /v1/books/{book_id}/resources:batchDelete` with `resource: "payroll_schedules"`, the confirmed schedule IDs, Payroll module access, and the normal idempotency controls. Treat `DELETE_CONFLICT` as authoritative and deactivate a referenced schedule instead - if an old hard-delete bug already left a posted invoice, bill, sales receipt, customer refund, receipt, expense, vendor refund, payment, payroll, inventory, or fixed-asset entry orphaned with no owning source row, confirm the source row is gone and then use `entries/{entry_id}:reverse` to repair the GL - when voiding or reversing a posted source-aware document such as an invoice, bill, sales receipt, customer refund, receipt, expense, vendor refund, or payment, set the economically correct `action_date`; when using generic `entries/{entry_id}:reverse`, set `reversal_date` instead; if the workflow-specific date is optional and omitted, Vibooks defaults it to today - financial reports follow posted entry dates, not the current document status alone ## Source-Document Extraction And Visual Confirmation OCR, scripts, parsers, and model extraction may prepare normal bookkeeping, but they are not source evidence. Treat every extracted field as a candidate until it has been checked against the original receipt, invoice, statement, payout report, or other source document. Before presenting a proposed entry to the user or posting a Vibooks resource, visually confirm every material field that is visible in the source document: - counterparty name and any relevant merchant, legal, or payee alias - document number, statement reference, or payout reference when present - document, transaction, payment, sale, expense, or statement date - currency - subtotal, statutory tax such as GST/HST, VAT, or sales tax, adjustments, tips, shipping, discounts, fees, and total - payment account, statement account, card, bank line, or payout line when visible from the evidence - item, account, category, tax code, or first-class workflow treatment when it is directly supported by the source document, saved master data, prior confirmed pattern, or user/accountant instruction Run deterministic arithmetic checks before relying on the proposal: - subtotal plus or minus adjustments plus statutory tax must reconcile to the total, allowing only rounding differences supported by the source document, tax rounding policy, or a clearly mechanical one-cent calculation difference - statutory tax amount must be plausible for the jurisdiction, tax code, and claimability available in the book - bank or card statement amount must reconcile to the payment, receipt, expense, bill payment, transfer, refund, settlement, or payout treatment Compare the visually confirmed source facts to the Vibooks create or correction payload before posting. If a material field is unreadable, missing, contradictory, or only supported by OCR or script output, do not silently fill it as confirmed. Ask the user, leave the field unresolved when the workflow allows it, or classify the proposed posting as needing user confirmation. When asking the user to confirm a proposed source-backed posting, include a brief readable check summary in the user's language: - visually confirmed fields - fields supported only by statement evidence, saved master data, prior confirmed pattern, or user/accountant explanation - unresolved fields and why they need confirmation - the proposed Vibooks workflow and accounting treatment Do not reuse stale OCR, parser, cache, or importer output from an earlier run as confirmation. Rendering a PDF to an image, cropping, zooming, rotating, enhancing readability, or using scripts for arithmetic is allowed because those steps help inspect the original evidence rather than replace it. ## Resource-Creation Rule When the user does not explicitly say which Vibooks business resources to create, infer and fill the normal first-class resources directly from the materials provided. Default priority: - if the materials identify a customer, vendor, invoice, bill, sales receipt, customer refund, receipt, expense, vendor refund, payment, item, bank statement line, or credit-card statement line, create or update those resources instead of waiting for the user to enumerate each one - create supporting master data such as `customers` or `vendors` when the source materials clearly establish the party and that master record is needed - create `items` when repeated products, services, or purchase categories clearly need reusable default accounts, tax codes, or prices - use `bank-lines` for real bank, debit-card, and credit-card statement lines when the materials are statement evidence - prefer first-class document workflows over manual journals when the materials support them - populate as many fields as the materials support, but do not invent parties, amounts, dates, tax treatment, currencies, or statement details - when the materials are source documents, populate material fields only after the extraction and visual-confirmation rule above has been satisfied - if the source materials are incomplete but still sufficient for a normal business-document workflow, create the supported resource and leave only the unsupported fields unresolved ## Customer Invoicing Use this workflow for customer sales, invoices, later collection, and customer prepayments. Inspect the live discovered schemas before acting; do not invent a field or lifecycle that the current contract does not expose. Choose the first-class sale before preparing lines: - use an `invoice` only for a sale on credit where accounts receivable should remain open - use a `sales-receipt` for a sale paid immediately; do not create an invoice and an immediate receipt merely to imitate a cash sale - when cash arrives after an invoice, create a `receipt` and use `receipt:apply`; applying the receipt settles AR and does not recognize the sale a second time - when cash arrives before an invoice or before revenue is earned, first record it as unapplied customer cash in the customer-deposit liability, then choose exactly one of the supported prepayment paths described below - if the user needs an unsupported advance, pro-forma, tax, or deferred-revenue invoice, stop and explain the boundary; do not post premature revenue or invent a normal invoice, recognition schedule, or generic-journal workaround Reuse or create the customer deliberately: - search the current book before creating a customer and reuse a trusted, active match; do not create casing, spelling, or alias duplicates - create a customer only when source evidence or confirmed user instruction establishes a new party - use the supported customer merge workflow for confirmed duplicate masters; never rewrite invoice or receipt history manually Decide whether the line needs an Item: - **Inventory goods:** require an active inventory-backed Item. Verify its inventory, COGS, sales, statutory tax, unit, quantity, and cost meaning. Never omit `item_id` from a real inventory sale, because that would omit the deterministic stock issue and COGS/inventory support posting. - **Repeated products and standardized services:** normally reuse or create an active `inventory`, `non_inventory`, or `service` Item when a stable name, unit, sales account, tax code, default price, or reporting identity will be used again. - **One-off non-inventory work:** an Item is optional when permanent catalog master data would have no continuing value. The explicit line must still contain an evidence-supported description, amount or quantity and unit price, sales account or supported default, statutory tax treatment, and required dimensions. Before creating an Item, search active Items by stable ID, code, SKU, exact name, and relevant aliases. Do not create one Item per invoice merely to retain free-form wording; keep transaction-specific detail in the line description. Stop instead of reusing an Item whose tax, account, inventory, or unit meaning conflicts with the sale. Treat all Item defaults as proposals: confirm that the current evidence still supports the account, tax code, price, unit, and dimensions, and use supported line overrides for a one-time exception instead of changing the shared Item. For every invoice proposal, review at least: - intended company, book, and customer - credit-sale status rather than immediate payment - `issue_date`, `posting_date` when different, required explicit ISO `due_date`, currency, and exchange rate when required. Payment terms may explain or support the proposed due date, but they are not a substitute API field; show the derivation and stop when the actual date is unresolved - each line's Item decision, description, quantity, unit price or amount, sales account or supported default, statutory tax code, tax-rounding evidence, and dimensions - separate non-tax fees, levies, tips, rebates, and similar components in `adjustments[]` rather than disguising them as tax - supporting attachment IDs and source provenance where available - an AR control-account override only when the book uses a supported non-default control account - whether the goods or services reached the recognition point supported by the book's policy; invoice date, cash receipt, and Item defaults are not proof by themselves Visually confirmed source facts, saved master data, prior confirmed patterns, and user statements remain distinct evidence sources. Never invent customer identity, delivery or performance completion, taxability, payment state, price, terms, due date, or recognition timing. After the user authorizes the proposal: 1. create the invoice through the live first-class endpoint with an idempotency key; never post normal AR through a generic journal 2. read it back and verify the documented customer, issue/posting/due dates, currency, line facts including stored `item_id`, tax, adjustments, total, amount due, attachments, and status 3. when an Item is used, read the current Item separately and verify its documented type, accounts, tax, unit, and inventory meaning; do not depend on undocumented Item-snapshot fields 4. verify AR and GL results; for inventory sales also verify the stock issue and COGS/inventory support posting 5. render the customer-facing document when the user needs a preview or handoff. Say that Vibooks rendered it; do not claim it was emailed, delivered, acknowledged, accepted, filed, or fiscally submitted without separate evidence Choose one prepayment lifecycle and do not mix them: - **Future-invoice settlement:** if a supported future invoice will create AR and the cash must settle it, keep the receipt unapplied in the customer-deposit liability and do not create a receipt recognition schedule. Create the invoice only when its supported recognition point is reached, then use `receipt:apply`. - **Direct deferred-revenue recognition:** use `receipt:create-recognition-schedule` only when evidence and the effective accounting policy support releasing the deposit liability directly without later applying this receipt to an invoice. Confirm the recognition account, start date, cadence, period count, dimensions, and performance facts; never infer them from payment date, invoice terms, or Item defaults. An active or paused non-cancelled receipt-linked recognition schedule and receipt application are mutually exclusive. Before applying, unapplying, replacing, cancelling, or reopening a receipt, read it and inspect `linked_recognition_schedules`. Do not retry or work around the protected conflict. To return the receipt to its ordinary lifecycle: 1. reverse every posted recognition line latest-first with `:reverseLatest`, reading the schedule after each reversal 2. cancel the schedule only after no posted lines remain 3. read back both the schedule and receipt 4. then apply or correct the receipt through the supported action and verify the resulting deposit, AR, revenue, and GL balances Obtain the normal authorization for every mutation. For invoice corrections, use void only before allocations, reopen a valid void when supported, replace a structurally wrong posted invoice through `:replace`, use `:replace-tax-code` for a tax-code-only correction, issue a credit note for a valid reduction of the remaining receivable, and use attachment actions when only evidence links changed. Never hard-delete, silently rewrite posted history, or use a generic journal as the primary invoice correction. ## Recurring Bookkeeping - create recurring templates for activity that repeats on a schedule and should stay first-class, such as rent bills, subscription invoices, monthly depreciation journals, or standing accruals - create `receipt:create-recognition-schedule` when a fully unapplied customer receipt should become deferred revenue - create `payment:create-recognition-schedule` when a fully unapplied vendor payment should become a prepaid expense - create `recognition-schedules` directly only when there is no better first-class source workflow for the originating balance-sheet position, such as accrued revenue or accrued expense entries - choose `invoice`, `bill`, or `entry` template kinds based on the real source workflow; do not turn recurring AR or AP into manual journals - do not use recurring templates to imitate prepaid or deferred recognition schedules line by line when one originating balance should be amortized or recognized over time - use `recognition-schedules/{scheduleId}:cancel` only before any due line has been posted; once releases are posted, reverse the latest release first and keep the source-aware trail intact - use `post-v1-books-book-id-recognition-schedules-schedule-id-post-due` to catch up every due recognition line through an `as_of` date - use `:reverseLatest` on the recognition schedule when the latest release was posted on the wrong date or into the wrong period; do not correct those schedule-backed entries with generic entry reverse - use `post-v1-books-book-id-recurring-templates-run-due` to catch up missed scheduled work through an `as_of` date - pause a recurring template when the business event has stopped temporarily; patch the schedule when the cadence changed; resume only after the next remaining occurrence is correct - for recurring journal templates, keep `source_type` business-meaningful and prefer a stable `source_ref_prefix` so generated entries remain auditable ## Customer-Facing Document Templates - use `document-templates` for customer- or vendor-facing HTML/PDF presentation of invoices, bills, sales receipts, purchase receipts, customer refunds, expenses, vendor refunds, receipts, and payments - do not use `recurring-templates` for presentation/layout; recurring templates create scheduled bookkeeping documents or journals - list `get-v1-books-book-id-document-templates` before editing so you can see built-in ids, current global defaults, current-book overrides, and supported `document_type` values - create a custom template with `post-v1-books-book-id-document-templates` using `name`, `document_type`, `scope` (`global` or `book`), `book_id` for book scope, and `html` - patch an existing custom template, or patch a built-in template id to store a built-in override; use `:reset` to clear a built-in override rather than deleting built-ins - use `:setDefault` on a global template for the global default, or on a book-scoped template for that book's default - render a real source document with `post-v1-books-book-id-documents-document-type-document-id-render`; omit `template_id` to use the effective default or pass a template id explicitly - template HTML supports escaped `{{variable_name}}` tokens such as `company_name`, `company_address`, `book_code`, `doc_title`, `doc_number`, `doc_date`, `doc_due_date`, `doc_party`, `doc_currency`, `doc_subtotal`, `doc_adjustment_total`, `doc_tax`, `doc_total`, `doc_amount_due`, `doc_description`, `generated_at`, `theme_color`, and `font_family` - helper HTML tokens are also available for conditional issuer/totals sections: `company_tax_id_html`, `company_address_html`, `company_contact_html`, `doc_subtotal_row_html`, `doc_tax_row_html`, `doc_adjustment_rows_html`, `doc_adjustment_summary_html`, and `doc_amount_due_row_html` - use `{{doc_adjustment_rows_html}}` inside line tables and `{{doc_adjustment_summary_html}}` inside totals blocks when the rendered document should show separate non-tax adjustments distinctly from subtotal and statutory tax - do not show `book_name` or `book_code` in customer-facing output unless a legacy customer template explicitly requires it; starter templates treat book identity as internal operator metadata ## Chart Of Accounts Rules Create a new account only when the reporting or reconciliation meaning is genuinely different. Common patterns: - bank account, checking account, debit card account, petty cash: `asset`, `debit`, `cash` or `bank`; when tied to statements, use statement role `bank_asset` - accounts receivable: `asset`, `debit`, `current_asset` - inventory: `asset`, `debit`, `inventory` - prepaid expense: `asset`, `debit`, `prepaid` - fixed asset: `asset`, `debit`, `fixed_asset` - vendor advances: `asset`, `debit`, `current_asset` - accounts payable: `liability`, `credit`, `current_liability` - credit card payable: `liability`, `credit`, `current_liability`; when tied to statements, use statement role `credit_card_liability` - customer deposits: `liability`, `credit`, `current_liability` - owner capital or retained earnings: `equity`, `credit`, `equity` - operating revenue: `revenue`, `credit`, `revenue` - other income: `revenue`, `credit`, `other_income` - cost of goods sold: `expense`, `debit`, `cost_of_sales` - normal operating expenses: `expense`, `debit`, `expense` - bank fees, interest expense, and FX loss: `expense`, `debit`, `other_expense` ## Date Rules Use the correct field for the correct date: - `transaction_date`: when the economic event happened - `posting_date`: when the ledger recognizes it - `issue_date`: the document date on an invoice or bill - `due_date`: the contractual due date - `sale_date`: the document date on a sales receipt - `refund_date`: the document date on a customer or vendor refund - `expense_date`: the document date on an immediate paid purchase - `receipt_date`: when cash was received - `payment_date`: when cash left the funding account - `deposit_date`: when already-held funds were deposited into the bank account - `statement_date`: the per-line date Vibooks uses for statement matching and reconciliation; use the financial institution's posting or clearing date when both transaction and posting dates are shown, retain the transaction date in the original evidence and the bank-line `reference` or `note`, and never use the statement period-end or closing date - `application_date`: when a receipt or payment is applied to AR or AP - `action_date`: the accounting date for cancellation or void workflows on posted source documents Posting rules: - invoice: use the invoice issue date - sales receipt: use the sale date - customer refund: use the refund date - invoice credit note or vendor credit: use the credit document's own date, not the parent invoice or bill date - bill: use the supplier bill date - expense: use the purchase date - vendor refund: use the refund date - receipt or payment: use the actual settlement date - bank deposit: use the date the deposit hits the bank account - bank fee, transfer, owner contribution, loan funding, loan repayment: use the evidence-supported transaction and posting dates under the payment method and book policy; do not use the statement period-end or closing date - accrual or month-end adjustment: use the last day of the affected period - opening balances: use one verified cutover date If a closed period must change, stop and ask before proceeding. ## Prefer First-Class Workflows Use: - `items` for reusable products, services, and inventory defaults that should populate source-document lines consistently - keep `item_id` on normal sales and purchase document lines whenever the activity is about a real tracked product or service, so the platform can apply the saved revenue, expense, inventory, COGS, and tax defaults - `invoice` for customer sales on credit - `sales-receipt` for customer sales paid immediately - `customer-refund` for customer returns, cash refunds, and customer-balance refunds - `receipt` then `receipt:apply` for customer cash collection - `bill` for vendor purchases on credit - `vendor-credit` for supplier credits, rebates kept on account, overbilled purchase corrections, and mixed bill-plus-over-credit situations that should stay on the vendor subledger until allocated to current or future bills - `expense` for immediate payee outflows that should not leave AP open, such as vendor purchases, loan repayments, owner draws, and tax remittances - `vendor-refund` for supplier cash refunds, card credits, and returned vendor advance balances that actually leave the supplier account and hit a funding account - `payment` then `payment:apply` for vendor settlement - `transfers` for bank, debit, cash, and credit-card statement-account movements between the business's own accounts - `settlements` for platform, payment-processor, POS-summary, OTA, and other external payout events where gross activity, fees, refunds, taxes, reserves, adjustments, and net cash settle together; use `lines[]` when the statement has variable processor components instead of forcing every amount into the fixed gross/tax/fee/refund/reserve fields - on invoices, bills, sales receipts, and expenses, use document `adjustments[]` for separate non-tax fee, levy, tip, rebate, or similar components instead of hiding them inside subtotal lines or tax setup - on document-mode customer refunds and vendor refunds, use `adjustments[]` only for separate non-tax components that belong on the same refund document; balance-mode refunds stay on `refund_amount` plus `refund_account_id` - choose the adjustment account explicitly: sales-side adjustments may post to revenue or liability accounts such as levy/remittance liabilities; purchase- side adjustments may post to the same business-account families allowed by the document workflow - use `mode: percent` only when the source component is a real percentage of the tax-exclusive subtotal; otherwise use `mode: fixed` - use `operator: subtract` for rebates, credits, and other non-tax reductions that belong on the same source document - if a charge, rebate, or deposit has its own tax treatment, quantity, item, or partial-credit semantics, keep it as a normal document line instead of an adjustment - `bank-deposits` when cash, undeposited funds, owner contributions, loan proceeds, direct income, customer-deposit holding balances, or similar non-statement source accounts are deposited into a bank statement account - `payroll-runs` for payroll results that post wages, withholdings, employer tax, liabilities, and cash settlement - `opening-balances` for cutover balances - `bank-lines` plus `reconciliations` for bank, debit, and credit-card statement accounts - `bank-lines/{lineId}:create-processor-settlement` only as a statement-line shortcut when the evidence is a payout that should still become a canonical `settlement` - for Stripe, payment processor, marketplace, POS, or OTA payout evidence, choose the accounting depth before posting: never record only the net bank deposit as revenue; either post a summary settlement from the payout report, or post customer/order-level sales first and then settle them. Customer-level `sales-receipt` detail is required when the user needs customer history, order-level reporting, refund tracing, or invoice-like support. Summary settlement is acceptable for anonymous POS, restaurant, retail, marketplace, or Stripe batches when the external report is retained as evidence and Vibooks only needs gross sales, tax, refunds, reserves, fees, adjustments, and net payout at the batch level - for Stripe, payment processor, marketplace, POS, or OTA evidence that identifies customer-level sales, create the customer sale first as a `sales-receipt` with `payment_account_id` set to the configured processor clearing account such as `Merchant Clearing`, then create a `settlement` for the payout. Prefer `settlement.lines[]`: gross/sales lines increase the payout and credit the same clearing account, fee/refund/reserve/custom deduction lines decrease the payout and debit their expense, refund, reserve, or clearing accounts. Link the settled sales with `sales_receipt_ids`, or put `sales_receipt_id` on the gross line when tracing one receipt to one processor component - if discovery does not expose `SalesReceiptCreateRequest.payment_account_id` or settlement `sales_receipt_ids`, do not invent hidden fields or bypass the workflow with manual journals; use the supported legacy settlement-only summary workflow, attach the processor evidence, and tell the user that customer-level Sales Receipt reporting requires a newer Vibooks version - manual journal entries only when no better workflow exists Subledger integrity rules: - invoices create receivables; receipts settle receivables through apply workflows - sales receipts recognize revenue and debit the selected payment account immediately; for direct cash sales that account is bank or cash, and for processor-funded sales it is a clearing account that remains open until the payout settlement - when a settlement links `sales_receipt_ids`, the settlement must clear the same processor payment account through gross/sales settlement lines; do not credit revenue again on the settlement - customer refunds either reverse immediate-sale revenue/tax lines or return customer deposits and overpayments without creating new AR - inventory item lines on customer refunds receive stock automatically and reverse the inventory versus COGS leg inside the same refund posting - bills create payables; payments settle payables through apply workflows - when goods arrive before the supplier bill, create a purchase receipt first, then create the later bill with `purchase_receipt_ids` so the bill clears the receipt accrual instead of receiving inventory a second time - expenses recognize the immediate outflow and funding movement immediately and do not leave AP open; expense lines may debit expense, asset, liability, or equity accounts as long as they are real non-statement business accounts - inventory item lines on invoices and sales receipts issue stock automatically and add the required COGS versus inventory support lines - inventory item lines on bills and expenses receive stock automatically into inventory instead of requiring a separate inventory receipt or adjustment - do not use purchase receipts for same-day billed purchases; use bills or expenses directly when the supplier tax document is already available - vendor credits create payable-side supplier credit that stays available for current or future bill allocation until `vendor-credit:apply` uses it up - vendor refunds either reverse purchase-side expense/asset and tax lines or return vendor advances or supplier cash back to the chosen funding account without creating new AP - inventory item lines on vendor refunds issue stock automatically using the refund line value instead of requiring a separate inventory issue - bank deposits debit the destination bank statement account and use signed source lines: positive lines credit non-statement sources such as undeposited funds, cash on hand, revenue, equity, loan liabilities, or customer-deposit holding balances; negative lines debit deductions such as merchant fees so the bank line stays at the net deposit - do not replace receipt or payment application with ad hoc journal lines against AR or AP control accounts - if a document or settlement uses a non-default control account, pass the explicit `ar_account_id` or `ap_account_id` at creation time and keep later apply, credit-note, and correction workflows on that same control account - if a posted supplier credit needs structural or tax correction, use the first-class `vendor-credit` workflow: `:unapply` it first when any bill allocations exist, then `:replace` the vendor credit itself; do not reverse the parent bill entry, and do not rely on a generic journal reverse as the primary correction path - if an upgraded book contains historical legacy bill credit-note entries, Vibooks migrates them into first-class `vendor-credit` records while keeping the original immutable journal rows for audit; all new supplier credits should use `vendor-credit` directly - use `unapplied_account_id` for real customer deposits or vendor advances that should remain open outside the main receivable or payable balance - do not record payroll through generic journal entries when the payroll workflow can express it - for supported Canadian payroll, configure the employee's effective-dated payroll profile, schedule, statutory payroll items, jurisdiction, and verified YTD history before calculation; use the employee payroll-calculation preview instead of entering tax deductions as operator-calculated amounts - before any Canadian payroll calculation preview, show the live request schema's unsupported special-tax-situation list to the operator. Send `unsupported_tax_situations_confirmed_absent: true` only after the operator confirms none applies; omission or `false` must stop the calculation. Review the returned `calculation.limitations` with the preview instead of discarding them - when pay, schedule, province, or tax setup changes on a later date, append a successor employee payroll profile through the payroll-profile API. The server atomically closes the unique predecessor on the prior calendar day and keeps historical selection intact. Never overwrite the earlier profile or patch its dates directly; same-start, future, or ambiguous overlaps fail closed and require reviewing the retained profile timeline - before an ordinary Canadian payroll post, read `/v1/books/{book_id}/payroll-rule-readiness`. Vibooks runs the same idempotent check automatically when Payroll opens and before calculation, batch creation, or posting. A headless client may POST that resource when it observes `pending`, but neither the operator nor the Agent certifies statutory rules. Use `calculation_state` and the actual server guard for calculation/posting eligibility. `pending` requires a fresh check; `blocked` requires reviewing the protected result or evidence that could not be replayed. A compatible checkpoint can produce `calculation_state: ready` while the legacy aggregate `status` remains `blocked`. Read `correction_state` and `remedy_status` separately; neither can be inferred from calculation eligibility. Do not choose an older revision, alter the posted payroll, or guess a replacement amount. Keep preview and correction planning available and follow the server's current correction target. Review actual-withholding matters through their retained correction detail; do not automatically reverse actual payments. Use the statutory reverse/replace workflow for other supported corrections, then refresh readiness before the next ordinary post. The legal interval is selected from the payroll pay date, not the activation date, current date, or date the user opens Vibooks - for a retained actual-withholding correction matter, discover the live `payroll-rule-correction-roots` routes and schemas. Start from the task's `root_id`/`detail_url`, or from a current readiness observation candidate: retain the observation and open its stable matter using separate idempotency keys. A candidate does not establish that a checkpoint is legally eligible. Read the original actual payroll, statement and journal links, current facts, blockers and `allowed_actions`. Follow only those exact action targets and request schemas: record evidenced intent, project a plan, review actual versus comparison amounts and zero financial effects, approve the exact plan, then execute. Execution leaves calculation pending until a fresh update check; the correction remains unresolved and its remedy requires determination. Do not treat a checkpoint as a refund, employee balance, authority credit, remittance, amended slip or filing authorization. An unavailable installed rule package cannot be replaced with a prior or caller-selected rule. - retain later claims, agreements, directions, refunds, offsets, credits, recoveries, payment conflicts or uncertain evidence through the matter's development action. Preserve unknown dates or money with a reason; never invent zero or infer an economic event from a source link. Use the current required fact revisions for every affected matter. Correct mistakes, subsequent changes and evidence-only additions through the explicit successor action, preserving the original history. Follow a server-offered revalidation intent through the same review stages when needed. After a stale conflict, reload current detail/history and preserve the operator's draft for review before a fresh submission. Follow every history cursor with unchanged filters; a first page is not the full audit history. On success, reload `detail_url` rather than treating an idempotent receipt as current permission or readiness. - for any payroll that may include provincial or territorial overtime, statutory-holiday pay, reporting or call-in pay, minimum-wage top-ups, scheduling effects, exemptions, or similar special pay, follow the on-demand official-source and professional-review workflow in `jurisdictions/ca/smb.md`. Vibooks does not determine those rules. Use native payroll only when an existing supported payroll item preserves the confirmed payment's exact meaning. Otherwise complete payroll through a qualified external process and retain its detailed result through the discovered external-payroll workflow. Do not call retired PEI setup, work-fact, tip/opening, special preview, or statutory-correction endpoints, relabel an unsupported amount, or turn an unknown amount into zero - use `/v1/books/{book_id}/tasks` as the shared Overview, Tasks, UI and Agent projection for open Payroll work. Preserve the complete versioned task ID, re-read its detail immediately before acting, and follow only the returned scope-aware action target. Never infer a correction from display copy or a cached member count. On `TASK_INSTANCE_CHANGED`, discard the stale task and review the replacement; on `TASK_VERIFICATION_REQUIRED`, complete the retained rule-impact check; when the task is no longer found, treat it as resolved. Count-only Payroll tasks are not dollar exposure - for an ordinary Canadian pay period on a light- or standard-approval book, use the guided payroll batch workflow: choose one schedule and exact period dates, preview every selected employee, review the server-returned totals and posting defaults, create one draft batch, approve it, and post it atomically; keep the individual-run workflow for genuine one-employee exceptions rather than preparing a normal multi-employee period one run at a time - send an explicit employee `calculation_mode`: use `profile_regular` for profile-derived salary or hourly pay with no item input, `itemized_regular` for a complete assigned regular earning set, and `profile_regular_with_items` for profile-derived salary or hourly pay plus assigned fixed deductions or employer contributions; never infer the mode from whether `payroll_items` happens to be present - regular item calculations support only assigned `regular_salary`, `regular_hourly`, `overtime`, `fixed_pre_tax`, `fixed_post_tax`, and `fixed_employer` meanings. Do not turn a percentage, bonus, retroactive pay, vacation payout, accumulated overtime, commission, taxable benefit, vacation-taken line, reimbursement, inactive item, or unknown future type into a fixed dollar amount; use its dedicated supported workflow or stop - generate one stable UUID `client_operation_id` and one stable idempotency key for a logical payroll-batch create. After an ambiguous response, read `/v1/books/{book_id}/payroll-batches/by-client-operation/{client_operation_id}` before retrying; reuse the same identifiers only for the exact unchanged request, and use stable action keys while reconciling approve or post results - guided payroll batches are intentionally unavailable for books whose current `approval_level` is `strict`. Stop on `PAYROLL_BATCH_STRICT_APPROVAL_UNSUPPORTED`; do not create an arbitrary approval, claim another principal, or suggest weakening the book policy - for Quebec employees, record the current-period Fonds de solidarité FTQ and Fondaction share-purchase withholdings on the payroll profile when they apply; preserve the combined prior-period amount in verified YTD history so current plus YTD never exceeds the official $5,000 annual limit. Vibooks records the full Q/Q1 amounts as employee deductions as well as applying the tax credit, so never repeat the same purchase in generic pre-tax or post-tax deductions and never combine Q/Q1 with the alternative 75% gross- remuneration-reduction method. Send explicit zero values outside Quebec so TP-1015.F factors `Q` and `Q1` are never inferred from a generic deduction line - let Vibooks select the statutory release from the book country, employee jurisdiction, and pay date; never request an older release, extend a prior release, or substitute a draft rule when the preview reports that no officially verified published release covers the date - treat missing payroll-rule coverage as an unsupported calculation boundary; retain the external provider calculation and source evidence when an external payroll workflow must be used instead of guessing statutory amounts - carry the preview's calculation snapshot, published release ID, formula ID, official verification identity, and fingerprint unchanged into the payroll batch or run; the server-authenticated keyed snapshot fingerprint also binds the normalized component posting contract, so do not rename, remove, reclassify, or change a calculated component even when aggregate totals would remain unchanged; ordinary reviewed account selections remain separate, but never supply a liability override for the canonical Quebec FTQ or Fondaction components, whose dedicated payable accounts are assigned by the server; use the payroll reversal, replacement, or correction workflow - every supported native Canadian payroll post must create its immutable pay statement in the same transaction. Select the employee and complete the pay-date-effective employer identity, employee payroll identity/code, and employee statement profile before posting. `/pay-statements/setup-readiness` is a current setup overview; it does not prove readiness for a different pay date or the exact payroll facts. Keep tax province separate from the explicit employment-standards jurisdiction and never infer federal coverage - a successful generic calculation preview is calculation evidence, not proof that the payroll can be posted. An employee name alone cannot supply the employee identity needed for a native pay statement. Follow actionable missing-field errors, complete the employee and statement setup, and use a fresh preview when protected facts change. Never strip calculation evidence or switch to an external payroll variant to bypass native statement checks - for every supported current period, submit exact typed `pay_statement_facts` to calculation preview. Saved hours are proposals only; confirm actual worked hours, hours paid/for which payment is made, salary hours only for salary profiles, and the permitted source kind. Do not send a caller-selected statement semantic: the versioned payroll item owns the earning meaning. Phase one ordinary periods require an explicit confirmation that there are no paid non-work hours - carry the server-returned statement facts, calculation snapshot and fingerprint unchanged into individual or batch post. A missing/mismatched fact, unpublished pay-date rule, unsupported earning meaning or incomplete setup must stop before any payroll, journal or statement mutation - reverse or replace Canadian payroll only with the complete retained employee/profile identity, calculation release/snapshot/fingerprint, pay-statement facts, detailed component arrays, cash account, date, and correction reason required by the typed request. For standard or strict approval, request `entry.reverse` approval for the exact request body and consume only an approved record whose `target_id` and `payload_hash` still match. If any date, fact, amount, account, or reason changes, request a new approval. Keep one stable idempotency key for the unchanged approval request and one for the unchanged final reverse or replacement until the outcome is known; after an ambiguous response, retry those exact identifiers instead of creating a second correction - after posting, use the statement list/detail/payroll-run-link/render and batch-export APIs. Viewing, downloading, printing or creating a ZIP does not prove delivery. Record `paper_in_person` only after the real handoff, with the exact retained language artifact and strict factual timestamp. This event does not assert payment, timeliness or legal qualification. Correct a mistake only through the append-only provision-event preview/commit correction APIs - Québec statement language is French unless an effective employee English request exists. UI language is irrelevant. Use shared English/French branded templates with the one protected statement-content slot; never hide or rewrite statutory content and never make province-specific appearance templates. A current request appends successor statements with retained English companions; when a future-dated request becomes effective, call `/employees/{employeeId}/pay-statement-language-companions:materialize` before rendering or handing off the English artifact - prepare CRA or Revenu Québec remittances only from the exact effective authority account, installed remitter calendar, active payroll sources, and unchanged preview fingerprint. `prepared` is not paid. Complete the real authority payment outside Vibooks, then call `:recordPayment` with its actual date, confirmation reference, funding account, and unchanged remittance fingerprint. That action atomically records the external-payment fact and posts the cash-to-payroll-liability settlement; do not post a separate expense or journal for the same payment. For an overpayment, provide a real authority- credit asset account instead of driving the payroll liability below zero. A corrected confirmation uses `:correctReference` and does not rewrite the journal. Reverse or replace a mistaken recorded payment only through `:withdrawPayment` or `:replacePayment` so the original fact, reversal entry, and successor stay in the append-only history. Do not substitute an installed monthly or quarterly calendar for an unsupported accelerated, weekly, or twice-monthly obligation, and do not claim authority receipt from the Vibooks record alone - review T4 data only through the discovered `/payroll-tax-forms/t4:preview` operation, using active immutable payroll, legal identity, opening YTD, and signed box-adjustment records. Correct boxes through `payroll-tax-form-adjustments` and its reversal action, not by editing payroll history. An omitted QPIP earnings box is not a zero correction basis: reconcile any signed box 56 adjustment to the retained eligible earnings. Resolve annual-limit and original-payment-order blockers using source records; do not replace missing chronology with the date an opening balance was entered. While the exact annual CRA form package is unavailable, there is no T4 artifact, PDF, download, print, or employee-copy workflow; do not call a removed preparation-artifact operation, construct a lookalike document, or reuse another tax year's form. A balanced preview is data review only and does not prove filing, acceptance, or distribution - prepare an ROE data-review report only after creating the employee interruption event, its employment-period boundary, each applicable typed statutory-payment fact, and a complete statutory-input coverage review. Then create the discovered ROE preparation artifact and use its retained render for handoff to the person completing and validating the official record in ROE Web. Before attempting any payroll-extract file, read `payroll_extract_export` from the discovered ROE preparation options. If `customer_export_ready` is false, do not construct or claim a `.BLK` file; retain the non-official review report and complete the record in ROE Web. Never put the full SIN or payroll account number in ordinary API fields. If Block 19 special payments or another unsupported field applies, stop instead of approximating it. Only Service Canada supplies the official ROE PDF after issue. Optional external-completion evidence records only what the user says happened outside Vibooks; it is not a Service Canada receipt - an ROE review-report correction creates a successor preparation artifact through the discovered successor operation, using the expected active head/fingerprint and a factual correction reason. Never overwrite the original report or its PDF. T4 data corrections instead use append-only box adjustments and their reversal action; no T4 artifact exists to replace while official PDF output is unavailable. A later verified form-definition revision or renderer release applies only to new output and remains independently identifiable from the payroll calculation release - use RL-1 previews only for year-end preparation from active immutable payroll, legal identity, opening YTD, and signed box-adjustment records. Until its verified annual PDF package and government workflow are installed, do not claim the preview was filed, accepted, or distributed; follow the authority's external filing process - for Canadian vacation pay, use the dedicated vacation resources for approved jurisdiction/class facts, service history, policy/arrangement, effective-dated accounts, opening, earning, period close, payment allocation, correction, and reporting; do not recreate vacation liability through generic payroll deductions or manual journals. Vacation post/reversal responses expose any pay-statement successor IDs; follow those immutable successors instead of continuing to use a superseded statement revision - treat each source earning meaning and earned-date segment as protected input; unknown semantics, uncovered dates, incomplete service or coverage, and rule gaps fail closed instead of falling back to taxable wages or a prior release; `effective_date` must equal the source payroll pay date and every segment must remain inside that immutable payroll period - when moving from Sage or another prior ledger, provide complete historical employee vacation detail decomposed into vacationable wages, statutory earned, contractual extra, statutory paid, contractual-extra paid, and owed by reference period; do not provide `rule_release_ids` because Vibooks selects the release. For NT, preserve evidenced provider-recorded earnings and payments; dated `nt_sources` inventory and attributions establish a separate current target, without replacing the imported balance. Other supported profiles validate statutory earned against their certified jurisdiction, service dates, wages, and cutover date. Split a row when a service-rate boundary requires dated detail; for a Québec protected-absence period, create the exact reviewed section-74 fact set first so the opening uses that official formula; positive employee openings must equal the source Vacation Pay Payable control total, and historical wages must never be inferred from a liability balance - for pay-each earnings, bind the exact posted payroll vacation-pay component; for a later retained payout, bind the exact component that debits Vacation Pay Payable and use its immutable payroll pay date. A matching payroll total, caller-supplied date, or label is not sufficient, and a payout cannot consume a balance earned after that pay date - after each retained accrual, true-up, payment, reversal, replacement, or control-account transfer, verify the employee vacation event balance equals the active Vacation Pay Payable balance and every reference period preserves `owed = recognized total - paid` with owed nonnegative. Recognized total is known statutory plus known contractual extra plus any explicitly recognized amount awaiting classification; that last amount is part of the total, not another liability or payment. Target credit never creates a second bucket or GL amount - for NT, retain actual same-employer service spells and the complete reviewed interval through `service-facts`; do not supply a guessed count of service years. Keep the stable vacation profile when revising service evidence. Retain a genuine employer policy through `policies` only when it establishes a total vacation-benefit floor on the same ordinary wage base. Never invent a policy to make an uncertain calculation proceed or silently raise an old numeric rate - NT earnings need actual amounts split at every applicable service, policy and rule boundary. An unresolved total cannot be posted. A genuine policy may establish the total while statutory/contractual classification remains unresolved; a null classification is not zero. Read `current_target` and `measurement_issues` separately from the immutable recognized/paid balances - read the current `authenticated_writer_id` from the employee's `service-facts` or `policies` response and use that identity as `approved_by` for NT corrections. This does not grant write permission. If the authenticated connection or its permissions change, reload and create a fresh preview; never reuse another reviewer's preview or substitute a historical author or default identity - use `reference-periods:correctionPreview` with the retained period and proposed date, then `post-correction` for an unchanged preview. Vibooks traces prior credit to the original dated rights, retains over-recognized amounts without automatic recovery, and adds only the supported shortfall. Do not net an excess on one dated right against another shortfall or treat rounded display shares as separate entitlements. Missing historical credit attribution may leave the current target known while blocking automatic correction - a zero-amount NT classification correction creates no payment or new capacity. A positive correction creates only its additional payable capacity; a `recognized_total` bucket means a confirmed amount available for allocation, not an additional economic category or a statutory/contractual split of past payments. Use the ordinary payroll-backed payment workflow for a later payout - financial reports and accountant exports preserve `measurement_status` and `measurement_issues`. A `qualified_draft` retains recorded ledger amounts but must not be presented as a fully measured vacation liability. This also applies to actual posted wages whose vacation obligation has not yet been recognized. For an explicit report date, later economic activity may prevent reconstruction; do not substitute today's correction or payment into the historical balance. Follow the identified employee and payroll source when no reference period exists. - unresolved NT measurement or an unapplied required correction blocks the affected book-period close; an exact reconciled total with classification pending can still close. Review the current vacation Task and report rather than treating an already paid recorded amount as proof of final settlement - vacation-payment allocation children are server-owned and use the documented oldest-due order; never submit caller-calculated children or account overrides - every vacation post and reversal needs a new `request_id` plus the reviewed `approved_by` identity. Retry only the exact same request. After a reversal, create a fresh supported replacement preview with `replaces_calculation_id` so the report retains the original, reversal, approver, and replacement chain. For an NT target correction, instead reassess the current reference period through its correction preview; the retained source and correction history determines whether any additional amount remains - if posting returns `VACATION_STRICT_APPROVAL_UNSUPPORTED`, stop and explain that vacation posting is unavailable while the book requires separate strict approvals. Do not change `approved_by`, retry, or recreate the result through a generic journal; ask the operator whether the book should use a supported light/standard approval mode - source files and AI extraction do not directly import vacation transactions. Analyze and visually verify the evidence, propose explicit facts, then call the same first-class preview/post/correction endpoints used by every client - keep vacation scope bookkeeping-only: do not represent PTO scheduling, leave approval, POS operation, or tip-pool allocation as Vibooks vacation features - use a full database backup and restore when moving natively authenticated payroll history; a portable book bundle cannot prove the source payroll key and must not turn an embedded, self-consistent component contract into native posting, remittance, or year-end evidence; an older portable snapshot retained only under a public integrity hash is marked untrusted by the receiving installation and remains blocked from automatic YTD and all statutory use until a complete append-only `legacy_run_attestation` links the posted run to retained source records and supplies every applicable employee and employer amount; never overwrite either the retained snapshot or attestation for later changes - before the first full backup, the owner must deliberately display the backup recovery code in the local desktop, save it outside the backup location, and confirm that separate copy. A backup from another or replacement installation must be previewed with that recovery code before restore. Agents must not call the reveal endpoint or pass a recovery code into backup preview/restore unless the user explicitly requests that local recovery operation. Never place a recovery code in chat, logs, filenames, bookkeeping evidence, or portable bundles - when purchase-side tax is only partly claimable, keep the statutory `tax_code_id` on the purchase line and set `tax_claimable_ratio` between `0` and `1`; Vibooks will keep the non-claimable portion inside the business line and only carry the claimable portion into tax returns - if a transaction is partially settled, keep the remaining open amount in the subledger instead of forcing full settlement - use inventory adjustments only for stock counts, shrinkage, spoilage, reclassifications, opening stock corrections, or other true exceptions; do not split normal buy/sell activity into both a source document and a second manual inventory movement Reimbursement and vendor-advance rule: - for employee reimbursements, owner-paid expenses, or other AP items that should settle through a dedicated payable such as `Reimbursement Payable`, create the bill and payment with the same `ap_account_id`, then use `payment:apply` on that same payables control account - when a bill was funded personally by an owner, shareholder, or other non-bank source, set `payment.funding_account` to the real balance-sheet funding account such as `Cash from owner` or `Shareholder Loan` - if the payment exceeds the open bill and should remain as a vendor advance or prepayment, route the excess through `unapplied_account_id` ## Common Posting Patterns - direct cash sale: prefer `sales-receipt`; economically it debits bank or cash and credits revenue - processor-funded customer sale: prefer `sales-receipt` with `payment_account_id` set to processor clearing, then a linked `settlement` when the payout arrives; economically the receipt debits clearing and credits revenue, while the settlement debits bank and fees and credits clearing - bank transfer or credit-card payment: prefer `transfers`; economically it debits the destination statement account and credits the source statement account - bank deposit: prefer `bank-deposits`; economically it debits the destination bank statement account, credits positive source lines such as cash, tax receivable, clearing, revenue, equity, loan, or holding balances, and debits negative deduction lines such as merchant fees so the deposit matches the bank's net amount - platform payout, merchant-processor remittance, OTA remittance, or other net settlement without customer-level sale evidence: prefer flexible `settlements` with `lines[]`; economically it ties gross activity, fees, refunds, reserves, taxes, custom adjustments, and net cash to one source-aware event - summary-based restaurant or small-lodging close: use sales receipts, expenses, receipts or payments, and settlements plus dimensions such as store, channel, or property; do not model POS or PMS front-office activity inside Vibooks - customer refund or deposit return: prefer `customer-refund`; economically it credits the funding account and debits revenue/tax reversal lines or a customer-balance liability - owner contribution: debit bank or cash, credit equity - owner draw: prefer `expense` for the withdrawal itself; debit drawings or equity and credit bank, card, or cash - loan proceeds: debit bank, credit loan payable - loan repayment: prefer `expense`; debit loan principal, debit interest expense if any, and credit bank for the full payment - tax remittance: prefer `expense`; debit the tax liability being settled and credit bank or cash - tax return preparation: prefer `tax-returns`; prepare a draft return for the filing period, review the summarized payable and recoverable rows, then file the return so Vibooks generates the settlement reclass entry through the chosen tax-settlement clearing account - debit-card purchase: prefer `expense`; economically it debits expense, prepaid, inventory, fixed asset, liability settlement, or equity draw lines and credits bank - credit-card purchase: prefer `expense`; economically it debits expense, prepaid, inventory, fixed asset, liability settlement, or equity draw lines and credits the specific card liability - vendor refund or rebate: prefer `vendor-refund`; economically it debits the receiving bank/card account or another real refund destination such as vendor advances, and credits expense, inventory/asset, tax, or a vendor-balance account - credit-card payment: debit the specific card liability; credit the paying bank account - payroll run: use the payroll workflow so wages, employee withholdings, employer tax, payroll liabilities, and cash settlement stay grouped as one payroll posting For credit cards, do not force card activity into a cash account just to use the statement reconciliation workflow. ## Opening Balances - use `post-v1-books-book-id-opening-balances`; obtain its current request schema through live discovery and describe before submitting - load only asset, liability, and equity balances at cutover; this operation does not accept revenue or expense accounts - the opening balance entry must tie to a verified prior balance sheet or opening trial balance - creation immediately posts the opening balance entry; do not attempt a separate opening-balance post action - read back the returned entry and verify its posted status, cutover dates, supporting evidence, and amounts against the source and ledger reports