jaz-clio 5.39.2 → 5.40.0

package/README.md

@@ -9,7 +9,7 @@
 
 <p align="center"><b>Jaz accounting on the command line, and inside any AI agent.</b></p>
 
-358 tools · 66 command groups · 7 skills · 13 calculators · 12 close playbooks · 158 field-tested API rules.
+358 tools · 66 command groups · 7 skills · 13 calculators · 12 close playbooks · 159 field-tested API rules.
 
 ```bash
 npm install -g jaz-clio
@@ -109,7 +109,7 @@ Several companies at once: comma-separate the keys, or use a personal access tok
 
 ## Skills
 
-158 API rules from production testing: field-name maps, error-recovery patterns, response-shape quirks, plus 12 job playbooks. Installable into any agent project, no server involved.
+159 API rules from production testing: field-name maps, error-recovery patterns, response-shape quirks, plus 12 job playbooks. Installable into any agent project, no server involved.
 
 ```bash
 clio init                     # auto-detect the agent, install skills + agent-rules

package/assets/skills/api/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: jaz-api
-version: 5.39.2
+version: 5.40.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
-  REST API. Covers field names, response shapes, 158 production gotchas, error
+  REST API. Covers field names, response shapes, 159 production gotchas, error
   recovery (422/400/404/500), search filters, pagination, and edge cases for
   every endpoint — invoices, bills, credit notes, journals, cash entries,
   payments, contacts, CoA, items, tax profiles, bank records, fixed assets,
@@ -547,3 +547,5 @@ When the user wants to OPEN, SEE, or SHARE something in the Jaz dashboard ("open
 - **jaz-jobs** — 12 accounting job playbooks (month-end close, bank recon, GST/VAT filing, etc.)
 - **jaz-conversion** — Data migration workflows from Xero, QuickBooks, Sage, MYOB, and Excel
 - **jaz-cli** — CLI command reference, auth, output formats, pagination, and workflow patterns
+
+160. **Payment `adjustment` is a CASH-LEG-only correction — it never moves the document balance.** Records an overpayment or a rounding difference on the bank side of a payment: `netCash = paymentAmount -/+ fees +/- adjustmentValue` (fees are deducted from cash received on an invoice and added to cash spent on a bill). AR/AP is untouched, so an overpaid invoice stays PAID with the excess sitting on the account you chose and NO credit note is created. Shape: `adjustment: { adjustmentValue, adjustmentAccountResourceId, adjustmentDescription? }` — signed, non-zero, max 2dp, always FLAT (never a percentage), never taxed. Accepted on `pay_invoice` / `pay_bill` / both credit-note refunds / `update_payment` / both receipt reconciliations. **NOT** on batch payments, and not for `DEBT_WRITE_OFF` / `CLEARING_SETTLEMENT` / `INTER_COMPANY` / `WITHHOLDING_TAX_CERTIFICATE` (those record a settlement, so there is no cash leg). The account must be non-controlled: not AR/AP, not the VAT or FX accounts, not bank/cash, not deposit-linked. **Write/read asymmetry:** you WRITE the nested `adjustment.adjustmentValue` but READ a flat `adjustmentAmount` on the payment record, alongside `adjustmentOrganizationAccountResourceId`. Don't confuse either with `lineItems[].taxVatAdjustment.adjustmentAmount`, which is line-item tax and unrelated. **On `update_payment`, omitting `adjustment` CLEARS it** — same as `transactionFee`, but NOT the same as `transactionFeeCollected`, which is preserved when omitted. On a reconciled payment that carries one, any update omitting it returns `PAYMENT_ADJUSTMENT_CANNOT_CHANGE_WHEN_RECONCILED` even if you only touched the reference.

package/assets/skills/api/references/endpoints.md

@@ -2081,8 +2081,26 @@ Update an existing payment record. All fields optional — only included fields
   "paymentMethod": "BANK_TRANSFER",
   "accountResourceId": "uuid-bank",
   "currency": { "sourceCurrency": "USD", "exchangeRate": 0.74 },
-  "transactionFee": 5.00,
-  "transactionFeeCollected": true
+  // Both fees are OBJECTS, not a number and not a boolean. A bare value is rejected.
+  "transactionFee": {
+    "feeAccountResourceId": "uuid-fee-expense",
+    "feeType": "FLAT",
+    "feeValue": 5.00,
+    "feeTaxVatApplicable": false
+  },
+  "transactionFeeCollected": {
+    "feeAccountResourceId": "uuid-fee-income",
+    "feeType": "FLAT",
+    "feeValue": 2.00,
+    "feeTaxVatApplicable": false
+  },
+  // Cash-leg adjustment: overpayment or rounding. Bank leg only, never AR/AP.
+  // Omitting this on an update CLEARS an existing adjustment.
+  "adjustment": {
+    "adjustmentValue": -0.03,
+    "adjustmentAccountResourceId": "uuid-rounding-account",
+    "adjustmentDescription": "rounding difference"
+  }
 }
 
 // Response: same shape as GET

package/assets/skills/api/references/errors.md

@@ -851,6 +851,22 @@ Journals support a top-level `currency` object to create entries in a foreign cu
 
 **Cashflow transaction ID ≠ payment ID** — These are different entities. Cashflow transactions are a ledger view; payment records are the actual payment objects attached to invoices/bills.
 
+#### Payment adjustment errors (422)
+
+The `adjustment` object on a payment is validated server-side. The API returns the code as `error_type` with a human message. Do NOT pre-validate any of these — surface the 422.
+
+Two of the seven never reach you through this path: a zero `adjustmentValue` and a missing `adjustmentAccountResourceId` are caught by the API layer's own field validation first and come back as a `validation_error`, not as the code below. `INVALID_PAYMENT_ADJUSTMENT_AMOUNT` still reaches you via the decimal-scale rule.
+
+| `error_type` | Cause | Fix |
+|---|---|---|
+| `INVALID_PAYMENT_ADJUSTMENT_AMOUNT` | `adjustmentValue` is zero, or has more than 2 decimal places | Send a non-zero value rounded to 2dp. Zero is the absence of an adjustment, not an adjustment of nothing — omit the object instead |
+| `PAYMENT_ADJUSTMENT_ACCOUNT_REQUIRED` | No `adjustmentAccountResourceId` | Supply one |
+| `INVALID_PAYMENT_ADJUSTMENT_ACCOUNT` | Account is a control account (AR, AP, the VAT pair, the FX accounts, Retained Earnings, withholding tax), a bank or cash account, deposit-linked, missing, or deleted | Pick an ordinary postable account. Most seeded accounts qualify — Rounding, Other Income, Bank Charges |
+| `PAYMENT_ADJUSTMENT_MAKES_NET_CASH_INVALID` | Net cash would not remain above zero | Reduce the magnitude of a negative adjustment |
+| `PAYMENT_ADJUSTMENT_NOT_APPLICABLE_FOR_PAYMENT_METHOD` | Method is `DEBT_WRITE_OFF`, `CLEARING_SETTLEMENT`, `INTER_COMPANY` or `WITHHOLDING_TAX_CERTIFICATE` | Those record a settlement, not a bank movement, so there is no cash leg to adjust. Drop the adjustment |
+| `PAYMENT_ADJUSTMENT_CANNOT_CHANGE_WHEN_RECONCILED` | The payment is matched to a bank statement entry and the request would change its adjustment | Un-reconcile first, or resend the existing adjustment unchanged. **This fires even when you are only editing `reference`**, because omitting `adjustment` reads as clearing it |
+| `PAYMENT_ADJUSTMENT_NOT_APPLICABLE_FOR_BATCH_PAYMENT` | Batch payments do not support adjustments | Record the adjustment on an individual payment |
+
 ---
 
 ### Sub-Resource Response Errors

package/assets/skills/api/references/feature-glossary.md

@@ -12,7 +12,7 @@ Sales documents sent to customers for goods/services rendered. Track Accounts Re
 
 Key capabilities: draft/approval workflows, multi-currency (auto-fetch ECB rates or custom org rates), scheduled/recurring invoices with dynamic scheduler strings, delivery slips, sales subscriptions with proration, bulk import (up to 1,000), Quick Fix for bulk field edits, GST/VAT adjustments.
 
-If payment date equals invoice date, it's recorded as a cash transaction (not AR). Transaction fees are deducted from cash received. RGL = `(Invoice payment / Transaction Rate) - (Cash received / Payment Rate)`.
+If payment date equals invoice date, it's recorded as a cash transaction (not AR). Transaction fees are deducted from cash received, and a payment `adjustment` shifts the cash leg further (net cash = paymentAmount - feesCharged + feesCollected +/- adjustmentValue) without touching AR. RGL = `(Invoice payment / Transaction Rate) - (Cash received / Payment Rate)`.
 
 **API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
 
@@ -38,7 +38,7 @@ Purchase documents from suppliers for goods/services received. Track Accounts Pa
 
 Key capabilities: bill receipts (short-form template creating bill + payment together), purchase order PDFs from drafts, scheduled/recurring bills, WHT certificate payments (always credited to WHT Payable account), bulk import.
 
-Transaction fees are added to cash spent (not deducted like invoices). RGL = `(Cash spent / Payment rate) - (Bill payment / Transaction rate)`.
+Transaction fees are added to cash spent (not deducted like invoices), and a payment `adjustment` shifts the cash leg further without touching AP. RGL = `(Cash spent / Payment rate) - (Bill payment / Transaction rate)`.
 
 **API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
 

package/assets/skills/api/references/field-map.md

@@ -636,6 +636,7 @@ Battle-tested patterns from production Jaz API clients:
 | `cashflowId` | ≠ `resourceId` | Cashflow transaction IDs are NOT payment IDs — different entities |
 | `bankAccountId` | `accountResourceId` | Bank account for the payment |
 | `fee` | `feeAmount` (response) / `transactionFee` (update) | Response field is `feeAmount`, update field is `transactionFee` |
+| `adjustment` (cash-leg over/underpayment) | `adjustment: { adjustmentValue, adjustmentAccountResourceId, adjustmentDescription }` | Write nested; READ back flat as `adjustmentAmount` + `adjustmentOrganizationAccountResourceId`. Bank leg only |
 | `isCrossCurrency` | `crossCurrency` | Boolean, no `is` prefix |
 | `currency` (string) | `currencyCode` (response) / `currency` (update: `{ sourceCurrency, exchangeRate }`) | Response is flat string, update is object |
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.39.2
+version: 5.40.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.39.2
+version: 5.40.0
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:

package/assets/skills/jaz-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-kit
-version: 5.39.2
+version: 5.40.0
 description: >-
   Use this skill when an accountant, bookkeeper, or owner is running real books
   in Jaz across one or more organizations from the terminal — setting up a

package/assets/skills/jaz-pseudo-sql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-pseudo-sql
-version: 5.39.2
+version: 5.40.0
 description: >-
   Use this skill when answering ad-hoc data questions that aren't covered by
   download_export (canonical reports — anomaly, audit, aging, P&L, BS, GL,

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.39.2
+version: 5.40.0
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.39.2
+version: 5.40.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires