jaz-clio 9.2.3 → 9.2.4

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 9.2.3
+version: 9.2.4
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 148 production gotchas, error
@@ -61,6 +61,7 @@ The rest of this skill (field names, gotchas, error catalog, dependency order, s
 6. **Payment bank account is `accountResourceId`**, not `bankAccountResourceId`.
 7. **Payments require 6 fields**: `paymentAmount`, `transactionAmount`, `accountResourceId`, `paymentMethod`, `reference`, `valueDate`.
 8. **Payments wrapped in `{ payments: [...] }`**, array recommended. Flat objects are now auto-wrapped by the API, but array format is preferred for clarity.
+8a. **On an invoice, bill or credit note update (`PUT`), `payments` (`refunds` on credit notes) edits payments by `resourceId`; it is not a replacement list.** An entry with a stored payment's `resourceId` (from `paymentRecords[]`) updates that payment in place and needs every payment field; `{ resourceId, deleted: true }` removes it; an entry without `resourceId` records a NEW payment; a stored payment left out stays as it is, unless the edit changes the document's total, currency or exchange rate: then every payment is deleted and its bank match released, and nothing records it again. `removedPaymentResourceIds` no longer exists and is ignored if sent. Never echo a stored payment without its `resourceId`: it is recorded a second time, or refused with `INVALID_PAYMENT_AMOUNT` on a fully paid document. Changing a payment's reference, date or method keeps its bank reconciliation; changing its amount releases it. A 422 applies nothing.
 
 ### Names & Fields
 9. **Line item descriptions use `name`**, not `description`.
@@ -357,7 +358,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 106. **Contact PUT uses `email` (string), not `emails` (array)**: GET returns `emails: [{email, label}]` (array) but PUT accepts `email: "user@example.com"` (string). Sending the `emails` array in PUT body causes 400 "Invalid request body". The CLI and tool executor handle this automatically via read-modify-write with the correct field.
 
 ### Quick Fix (Bulk Update)
-107. **24 Quick Fix endpoints for bulk-updating transactions and line items**: `POST /api/v1/quick-fix/{entity}` with `{ resourceIds: [...], attributes: {...} }`. Only included fields are changed; omitted fields are left unchanged. Response: `{ updated: string[], failed: [{ resourceId, error, errorCode }] }`. **HTTP status codes**: 200 = complete success (`failed` always empty). **207 Multi-Status** = partial or total failure with per-item detail (same response shape as 200, so check the `failed` array). 422 = total failure with no per-item breakdown (rare). On 207, retry only `failed` resourceIds. Entities: **ARAP**: invoices, bills, customer-credit-notes, supplier-credit-notes. **Accounting**: journals, cash-entries. **Schedulers**: sale-schedules, purchase-schedules, subscription-schedules, journal-schedules. **Orders (line items only, no transaction-level route)**: sale-orders, sale-quotes, purchase-orders, purchase-requests. **Line-item request patterns**: ARAP, accounting and orders use `{ lineItemResourceIds, attributes }` (purchase side adds `withholdingTax`). **Line-item `discount` and `withholdingTax` use the quick fix shapes, not the create/update ones**: `discount: { rateType: "PERCENTAGE"|"FLAT", rateValue }` (not a bare number) and `withholdingTax: { code, rate, rateType, type, description? }` (code, rate, rateType and type all required), on bills, supplier CNs and purchase orders/requests alike. Schedulers (sale/purchase/subscription) use Pattern C: `{ schedulerUpdates: [{ schedulerResourceId, lineItemUpdates: [{ arrayIndex, attributes: {...} }] }] }` (fields INSIDE `attributes`; beside `arrayIndex` the API drops them and still reports success). **Journal-schedules use Pattern D**: `lineItemResourceId` (UUID) instead of `arrayIndex`. **Field gotchas**: the API drops any unknown field and still lists the record as updated, so clio refuses a field the entity does not take (per-entity list: endpoints.md, generated from the spec). Currency change: `currencySettings: { sourceCurrencyCode }` (not the create shape `currency: { sourceCurrency }`); lines and tax profiles stay. Cash entries use `currencySetting` (singular: `{ rateFunctionalToSource, exchangeToken }`), NOT `currencySettings`. Journal schedules have `startDate` in addition to `endDate`/`interval`. Tags: string array, max 50 items, max 50 chars each; on invoices, bills and credit notes they total at most 1000 characters joined with `|`, else 422. **Line-item `classifierConfig`** sets or removes one classifier per entry: set = `{ resourceId, type, printable, selectedClasses }` with at least one class; remove = `{ resourceId, deleted: true }`; classifiers not named stay; `[]` changes nothing. A 207 `failed` entry can carry an empty `resourceId` when the failure matched no record.
+107. **24 Quick Fix endpoints for bulk-updating transactions and line items**: `POST /api/v1/quick-fix/{entity}` with `{ resourceIds: [...], attributes: {...} }`. Only included fields are changed; omitted fields are left unchanged. Response: `{ updated: string[], failed: [{ resourceId, error, errorCode }] }`. **HTTP status codes**: 200 = complete success (`failed` always empty). **207 Multi-Status** = partial or total failure with per-item detail (same response shape as 200, so check the `failed` array). 422 = total failure with no per-item breakdown (rare). On 207, retry only `failed` resourceIds. Entities: **ARAP**: invoices, bills, customer-credit-notes, supplier-credit-notes. **Accounting**: journals, cash-entries. **Schedulers**: sale-schedules, purchase-schedules, subscription-schedules, journal-schedules. **Orders (line items only, no transaction-level route)**: sale-orders, sale-quotes, purchase-orders, purchase-requests. **Line-item request patterns**: ARAP, accounting and orders use `{ lineItemResourceIds, attributes }` (purchase side adds `withholdingTax`). **Line-item `discount` and `withholdingTax` use the quick fix shapes, not the create/update ones**: `discount: { rateType: "PERCENTAGE"|"FLAT", rateValue }` (not a bare number) and `withholdingTax: { code, rate, rateType, type, description? }` (code, rate, rateType and type all required), on bills, supplier CNs and purchase orders/requests alike. Schedulers (sale/purchase/subscription) use Pattern C: `{ schedulerUpdates: [{ schedulerResourceId, lineItemUpdates: [{ arrayIndex, attributes: {...} }] }] }` (fields INSIDE `attributes`; beside `arrayIndex` they are unknown keys). **Journal-schedules use Pattern D**: `lineItemResourceId` (UUID) instead of `arrayIndex`. **Field gotchas**: an unknown field is a 400 that names it, and clio refuses it before sending (per-entity list: endpoints.md, generated from the spec). A change to a paid document's currency or rate, a line's quantity, price, discount or tax, or the date of a foreign-currency document (its rate is fetched again) deletes its payments as in Rule 8a. Currency change: `currencySettings: { sourceCurrencyCode }` (not the create shape `currency: { sourceCurrency }`); lines and tax profiles stay. `sourceCurrencyCode` is required even when only `rateFunctionalToSource` changes (422 without it), and schedules also need the rate. `billFrom`/`billTo`/`creditFrom`/`creditTo` need `name` and `billingAddress` (plus `shippingAddress` on `billTo`/`creditTo`), each address with `addressLine1`; the address is replaced, not merged, so resend stored values you are not changing. Cash entries use `currencySetting` (singular: `{ rateFunctionalToSource, exchangeToken }`), NOT `currencySettings`. Journal schedules take `endDate`/`interval`, not `startDate` (a schedule's start date cannot change). Sale and subscription schedule lines refuse `withholdingTax`. Tags: string array, max 50 items, max 50 chars each; on invoices, bills and credit notes they total at most 1000 characters joined with `|`, else 422. **Line-item `classifierConfig`** sets or removes one classifier per entry: set = `{ resourceId, type, printable, selectedClasses }` with at least one class; remove = `{ resourceId, deleted: true }`; classifiers not named stay; `[]` changes nothing. A 207 `failed` entry can carry an empty `resourceId` when the failure matched no record.
 107a. **Ledger Find & Fix: find and fix (recode) records across types with one filter, preview one change, apply it once.** Use it when a user asks to find & fix, recode, reclassify, retag, re-date or move records to another account across many records or several types. `POST /api/v1/ledger/find-fix/transactions/preview` (sets contact, date, capsule, tags) or `POST /api/v1/ledger/find-fix/line-items/preview` (sets account, classifiers), each with `{ filter, change }`, then `POST /api/v1/ledger/find-fix/apply` with `{ previewId }`; conditions, bodies and every code are in endpoints.md section 17a. `JOURNAL` covers manual and cashflow journals only: transfer and trial-balance journals and cash transfers never match, so their ids come back `NOT_FOUND`. **A filter with no condition besides `types` is a 422, and a condition with no operator is ignored.** **The API refuses a key it does not take, at any level, with 400 `invalid_filter` naming the key**; the tools and the CLI refuse a field of the other level before the request, naming the level that takes it. `tags` `{ add, remove }` keeps the record's other tags, so setting tags to X means removing the current ones and adding X. A classifier removal needs only `{ resourceId, deleted: true }`, even for a classifier the organization no longer has. **Preview** writes nothing, matches at most 500 records, and returns `previewId` (valid 30 minutes; absent when nothing is eligible). **A blocked field is left as it is while the record's other fields still change.** **Apply** is single use and saves the preview-time values, so a field edited between preview and apply, tags included, is overwritten. Once it has taken the preview it runs to the end even if the caller leaves, and starts no new call 3 minutes after the request arrived. 207 lists the `failed` records with an `errorCode`; `OUTCOME_UNKNOWN` means that record may have changed. 404 `PREVIEW_NOT_FOUND` (expired, used, being applied, or another caller's): preview again, never resend. **Any other 5xx, or a timeout, on apply means the outcome is unknown: if the connection drops, the apply keeps running for up to 4 minutes. Wait that long before previewing or applying again on the same records, then preview again or re-read them. Never apply this previewId again.** Several applies can run at the same time. When two applies change records on one document at once, the one saved last can undo the other's changes, including fields and line items it did not set. Preview again to check the result. Lock dates, filed tax periods and claims-backed documents fail per record, and e-invoice filings may be re-submitted. Rule 107's per-type routes stay for one document, for fields this does not change (due date, tax profile, notes, amounts, custom fields) and for scheduled transactions.
 
 ### Transfer Trial Balance
@@ -370,7 +371,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 110. **Bank rule placeholder strings**: Bank reconciliation rules support dynamic strings in any free text field (`name`, `reference`, cash entry description). Strings are replaced with actual **bank record** values during reconciliation: `{{bankReference}}` → bank record reference (e.g., INV-03/01/2025-01), `{{bankPayee}}` → payer/payee name (e.g., Fruit Planet), `{{bankDescription}}` → transaction description (e.g., QR Payment). Example: `reference: "{{bankPayee}} - {{bankReference}}"`.
 
 ### Quick Fix Tag Field
-111. **Quick-fix uses `tags` (string array), e.g., `"tags": ["Q1"]`**: The `attributes` object in quick-fix transaction endpoints accepts `tags` as a string array (e.g., `"tags": ["Q1"]`). `tag` (singular) is silently ignored. This matches the `tags` array format used on create/update for all transaction types. The CLI `--tag` flag auto-wraps to `tags: [name]`.
+111. **Quick-fix uses `tags` (string array), e.g., `"tags": ["Q1"]`**: The `attributes` object in quick-fix transaction endpoints accepts `tags` as a string array (e.g., `"tags": ["Q1"]`). `tag` (singular) is refused as an unknown key. This matches the `tags` array format used on create/update for all transaction types. The CLI `--tag` flag auto-wraps to `tags: [name]`.
 
 ### Sub-Resource Response Shapes
 112. **Invoice/bill payment & credit sub-resources: two shapes** (read from the API source; payments and the empty-credits case measured raw 2026-09-24). `GET /invoices/:id/payments` and `GET /bills/:id/payments` return `{ data: [{paymentRecord}, ...] }` (Rule 64). `GET /invoices/:id/credits` and `GET /bills/:id/credits` return `{ TotalElements, data: [...] }` when credits are applied but a BARE `[]` when none are. The CLI and tools normalize all of these to `{data: [...]}`. `DELETE /invoices/:id/credits/:creditsAppliedResourceId` reverses a credit application.

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

@@ -2092,7 +2092,7 @@ Only included fields are changed; omitted fields are left unchanged.
 - **cash-entries**: `capsuleResourceId`, `contactResourceId`, `currencySetting {exchangeToken, rateFunctionalToSource}`, `organizationAccountResourceId`, `reference`, `tags`, `taxCurrencySettings {exchangeRate, sourceCurrency}`, `valueDate`
 - **customer-credit-notes**: `capsuleResourceId`, `contactResourceId`, `creditFrom {billingAddress {addressLine1, addressLine2, city, country, postalCode, state}, name, taxId}`, `creditTo {billingAddress {addressLine1, addressLine2, city, country, postalCode, state}, name, shippingAddress {addressLine1, addressLine2, city, country, postalCode, state}, taxId}`, `currencySettings {exchangeToken, rateFunctionalToSource, sourceCurrencyCode}`, `customFields`, `notes`, `tags`, `taxCurrencySettings {exchangeToken, rateFunctionalToSource, sourceCurrencyCode}`, `templateResourceId`, `valueDate`
 - **invoices**: `billFrom {billingAddress {addressLine1, addressLine2, city, country, postalCode, state}, name, taxId}`, `billTo {billingAddress {addressLine1, addressLine2, city, country, postalCode, state}, name, shippingAddress {addressLine1, addressLine2, city, country, postalCode, state}, taxId}`, `capsuleResourceId`, `contactResourceId`, `currencySettings {exchangeToken, rateFunctionalToSource, sourceCurrencyCode}`, `customFields`, `dueDate`, `invoiceNotes`, `tags`, `taxCurrencySettings {exchangeToken, rateFunctionalToSource, sourceCurrencyCode}`, `templateResourceId`, `valueDate`
-- **journal-schedules**: `capsuleResourceId`, `contactResourceId`, `endDate`, `internalNotes`, `interval`, `startDate`, `tags`
+- **journal-schedules**: `capsuleResourceId`, `contactResourceId`, `endDate`, `internalNotes`, `interval`, `tags`
 - **journals**: `capsuleResourceId`, `contactResourceId`, `internalNotes`, `tags`, `valueDate`
 - **purchase-schedules**: `capsuleResourceId`, `contactResourceId`, `currencySettings {exchangeToken, rateFunctionalToSource, sourceCurrencyCode}`, `customFields`, `endDate`, `interval`, `tags`, `taxCurrencySettings {exchangeToken, rateFunctionalToSource, sourceCurrencyCode}`
 - **sale-schedules**: `billFrom {billingAddress {addressLine1, addressLine2, city, country, postalCode, state}, name, taxId}`, `billTo {billingAddress {addressLine1, addressLine2, city, country, postalCode, state}, name, shippingAddress {addressLine1, addressLine2, city, country, postalCode, state}, taxId}`, `capsuleResourceId`, `contactResourceId`, `currencySettings {exchangeToken, rateFunctionalToSource, sourceCurrencyCode}`, `customFields`, `endDate`, `interval`, `invoiceNotes`, `tags`, `taxCurrencySettings {exchangeToken, rateFunctionalToSource, sourceCurrencyCode}`, `templateResourceId`

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 9.2.3
+version: 9.2.4
 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: 9.2.3
+version: 9.2.4
 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: 9.2.3
+version: 9.2.4
 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: 9.2.3
+version: 9.2.4
 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: 9.2.3
+version: 9.2.4
 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: 9.2.3
+version: 9.2.4
 description: >-
   Use this skill when modeling complex multi-step accounting transactions:
   anything that spans multiple periods, involves changing amounts, or requires