jaz-clio 4.30.9 → 4.30.10

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.30.9
+version: 4.30.10
 description: Complete reference for the Jaz REST API — the accounting platform backend. Use this skill whenever building, modifying, debugging, or extending any code that calls the API — including API clients, integrations, data seeding, test data, or new endpoint work. Contains every field name, response shape, error, gotcha, and edge case discovered through live production testing.
 license: MIT
 compatibility: Requires Jaz API key (x-jk-api-key header). Works with Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, and any agent that reads markdown.
@@ -243,7 +243,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 92c. **Valid enums** — `depreciationMethod`: `STRAIGHT_LINE`, `NO_DEPRECIATION`. `category`: `TANGIBLE`, `INTANGIBLE`. Optional string fields (`purchaseBusinessTransactionResourceId`, `accumulatedDepreciationAccountResourceId`, `capsuleResourceId`) can be safely omitted — the API ignores empty values.
 
 ### Subscriptions & Scheduled Transactions
-93. **Subscription endpoints are under `/scheduled/subscriptions`** — List, GET, POST, PUT, DELETE all at `/api/v1/scheduled/subscriptions[/:id]`. Cancel is at `/api/v1/scheduled/cancel-subscriptions/:id` (different path pattern). **Subscriptions are invoices only** (SALE) — no bills. Different from scheduled invoices: subscriptions auto-prorate partial periods (generate credit notes for mid-period changes), but currency/tax/account are immutable after creation. Use scheduled invoices for fixed-amount recurring invoices where you need per-occurrence flexibility.
+93. **Subscription endpoints are under `/scheduled/subscriptions`** — List, GET, POST, PUT, DELETE all at `/api/v1/scheduled/subscriptions[/:id]`. Cancel is **PUT** (not POST) at `/api/v1/scheduled/cancel-subscriptions/:id` (different path pattern). **Subscriptions are invoices only** (SALE) — no bills. Different from scheduled invoices: subscriptions auto-prorate partial periods (generate credit notes for mid-period changes), but currency/tax/account are immutable after creation. Use scheduled invoices for fixed-amount recurring invoices where you need per-occurrence flexibility. **All subscription CRUD requires `proratedConfig: { proratedAdjustmentLineText: string }`**. Cancel requires `cancelDateType` (`END_OF_CURRENT_PERIOD`, `END_OF_LAST_PERIOD`, `CUSTOM_DATE`) + `proratedAdjustmentLineText` + `resourceId` in body. Must cancel before delete. `businessTransactionType` is NOT in the OAS — the API ignores it.
 94. **Scheduled transaction search does NOT support `createdAt` sort** — `POST /scheduled-transaction/search` sort fields: `startDate`, `nextScheduleDate`, etc. Default to `startDate` DESC. This is a cross-entity search across all scheduled types (invoices, bills, journals, subscriptions).
 
 ### Universal Search

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

@@ -1320,6 +1320,75 @@ Same but with `"bill"` wrapper instead of `"invoice"`.
 
 ---
 
+## 16b. Subscriptions (Recurring Invoices with Auto-Proration)
+
+Subscriptions auto-generate invoices on schedule with proration support. **Different from scheduled invoices**: subscriptions auto-prorate partial periods (generate credit notes for mid-period changes), but currency/tax/account are immutable after creation. Invoices only — no bills.
+
+### POST /api/v1/scheduled/subscriptions
+
+```json
+// Request:
+{
+  "repeat": "MONTHLY",
+  "startDate": "2026-04-01",
+  "status": "ACTIVE",
+  "proratedConfig": {
+    "proratedAdjustmentLineText": "Prorated adjustment"
+  },
+  "invoice": {
+    "contactResourceId": "uuid-customer",
+    "reference": "SUB-001",
+    "valueDate": "2026-04-01",
+    "dueDate": "2026-04-30",
+    "lineItems": [
+      { "name": "Monthly Retainer", "unitPrice": 3000, "quantity": 1, "accountResourceId": "uuid-revenue" }
+    ],
+    "saveAsDraft": false
+  }
+}
+
+// Response:
+{ "data": { "resourceId": "uuid" } }
+```
+
+**CRITICAL notes**:
+- `proratedConfig` is **REQUIRED** on create, update, and cancel. Omitting it causes 500 (server null pointer).
+- `businessTransactionType` is NOT in the OAS — the API ignores it. Don't send it.
+- Uses `repeat` + `invoice` wrapper — same structure as scheduled invoices (`POST /scheduled/invoices`).
+- `repeat`: `"WEEKLY"`, `"MONTHLY"`, `"QUARTERLY"`, `"YEARLY"`.
+- `saveAsDraft: false` is REQUIRED inside the `invoice` wrapper.
+- Currency, tax, and account details are the SAME for all items and CANNOT be changed after creation.
+- Mid-period cancellations or amount changes auto-generate prorated credit notes.
+
+### PUT /api/v1/scheduled/cancel-subscriptions/:id
+
+Cancel is **PUT** (not POST). Requires body fields — empty `{}` returns 422.
+
+```json
+// Request:
+{
+  "cancelDateType": "END_OF_CURRENT_PERIOD",
+  "proratedAdjustmentLineText": "Prorated adjustment",
+  "resourceId": "uuid-subscription"
+}
+
+// Response:
+{ "data": { "resourceId": "uuid", "status": "SUCCEEDED" } }
+```
+
+`cancelDateType` values: `END_OF_CURRENT_PERIOD` (default), `END_OF_LAST_PERIOD`, `CUSTOM_DATE` (requires `endDate: "YYYY-MM-DD"`).
+
+Note the different path pattern from CRUD: cancel is at `/scheduled/cancel-subscriptions/:id`, not `/scheduled/subscriptions/:id/cancel`. Must cancel before delete — cannot delete ACTIVE subscriptions.
+
+### Other subscription endpoints
+
+- `GET /api/v1/scheduled/subscriptions` — List all subscriptions
+- `GET /api/v1/scheduled/subscriptions/:id` — Get subscription details
+- `PUT /api/v1/scheduled/subscriptions/:id` — Update subscription (requires `proratedConfig`, `repeat`, `resourceId`)
+- `DELETE /api/v1/scheduled/subscriptions/:id` — Delete subscription (must be cancelled first)
+
+---
+
 ## 17. Reports
 
 ### POST /api/v1/generate-reports/trial-balance

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

@@ -574,6 +574,22 @@ if (acct.code) ctx.coaIds[acct.code] = acct.resourceId;
 
 ---
 
+## Subscriptions Errors
+
+### 500 Internal Server Error — missing `proratedConfig`
+**Cause**: `POST /scheduled/subscriptions` and `PUT /scheduled/subscriptions/:id` return 500 when `proratedConfig` is omitted. The server null-pointer dereferences on the missing field. OAS marks it required but the 500 is misleading.
+**Fix**: Always include `proratedConfig: { proratedAdjustmentLineText: "Prorated adjustment" }` in create and update bodies.
+
+### 422 on cancel — wrong method or missing fields
+**Cause**: Cancel endpoint is **PUT** `/scheduled/cancel-subscriptions/:id` (not POST). Requires body: `{ cancelDateType, proratedAdjustmentLineText, resourceId }`. Empty `{}` returns 422.
+**Fix**: Use PUT with required fields. `cancelDateType`: `END_OF_CURRENT_PERIOD` (default), `END_OF_LAST_PERIOD`, `CUSTOM_DATE`.
+
+### Cannot delete ACTIVE subscription
+**Cause**: `DELETE /scheduled/subscriptions/:id` fails if subscription status is ACTIVE.
+**Fix**: Cancel first, then delete.
+
+---
+
 ## Deposits Errors
 
 ### 404 — Endpoint does not exist

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

@@ -18,6 +18,20 @@ If payment date equals invoice date, it's recorded as a cash transaction (not AR
 
 ---
 
+## Subscriptions (Recurring Invoices with Proration)
+
+Auto-generates invoices on a recurring schedule (weekly, monthly, quarterly, yearly) with automatic proration for mid-period adjustments. When dates or amounts change, prorated invoices or credit notes are generated for partial periods.
+
+**Key differences from scheduled invoices**: Subscriptions auto-prorate (scheduled invoices don't). But currency, tax, and account details must be the same for all line items and cannot be changed after creation (scheduled invoices allow per-occurrence flexibility).
+
+Use subscriptions for: software licenses, retainer services, SaaS billing — any recurring revenue where proration matters. Use scheduled invoices for fixed-amount recurring invoices where you need to change line items, tax, or currency per occurrence.
+
+**Invoices only** — no bills. `businessTransactionType` must be `"SALE"`.
+
+**API**: CRUD `GET/POST/PUT/DELETE /scheduled/subscriptions`, cancel `POST /scheduled/cancel-subscriptions/:id`, search `POST /scheduled-transaction/search` (cross-entity).
+
+---
+
 ## Bills
 
 Purchase documents from suppliers for goods/services received. Track Accounts Payable with multi-currency FX. Bills follow the same lifecycle as invoices but with reversed RGL logic and admin-only approval workflows. Supports withholding tax (WHT) on line items.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.30.9
+version: 4.30.10
 description: Accounting data conversion skill — migrates customer data from Xero, QuickBooks, Sage, MYOB, and Excel exports to Jaz. Covers config, quick, and full conversion workflows, Excel parsing, CoA/contact/tax/items mapping, clearing accounts, TTB, and TB verification.
 ---
 

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 4.30.9
+version: 4.30.10
 description: 12 accounting jobs for SMB bookkeepers and accountants — month-end, quarter-end, and year-end close playbooks plus 9 ad-hoc operational jobs (bank recon, document collection, GST/VAT filing, payment runs, credit control, supplier recon, audit prep, fixed asset review, statutory filing). Jobs can have paired tools as nested subcommands (e.g., `clio jobs bank-recon match`, `clio jobs document-collection ingest`, `clio jobs statutory-filing sg-cs`). Paired with an interactive CLI blueprint generator (clio jobs).
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill. For individual transaction patterns, load the jaz-recipes skill.

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 4.30.9
+version: 4.30.10
 description: 16 IFRS-compliant recipes for complex multi-step accounting in Jaz — prepaid amortization, deferred revenue, loan schedules, IFRS 16 leases, hire purchase, fixed deposits, asset disposal, FX revaluation, ECL provisioning, IAS 37 provisions, dividends, intercompany, and capital WIP. Each recipe includes journal entries, capsule structure, and verification steps. Paired with 13 financial calculators that produce execution-ready blueprints with workings.
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill alongside this one.

package/dist/commands/subscriptions.js

@@ -103,17 +103,20 @@ export function registerSubscriptionsCommand(program) {
                     ...(opts.taxProfile && !li.taxProfileResourceId ? { taxProfileResourceId: opts.taxProfile } : {}),
                 }));
             }
+            // Subscriptions use repeat + invoice wrapper + proratedConfig (required)
             body = {
-                businessTransactionType: 'SALE',
-                interval: opts.interval,
+                repeat: opts.interval,
                 startDate: opts.startDate,
                 status: 'ACTIVE',
-                contactResourceId: opts.contact,
-                reference: opts.ref,
-                valueDate: opts.date,
-                dueDate: opts.due,
-                lineItems,
-                saveAsDraft: false,
+                proratedConfig: { proratedAdjustmentLineText: 'Prorated adjustment' },
+                invoice: {
+                    contactResourceId: opts.contact,
+                    reference: opts.ref,
+                    valueDate: opts.date,
+                    dueDate: opts.due,
+                    lineItems,
+                    saveAsDraft: false,
+                },
             };
             if (opts.endDate)
                 body.endDate = opts.endDate;
@@ -163,12 +166,19 @@ export function registerSubscriptionsCommand(program) {
     })(opts));
     cmd
         .command('cancel <resourceId>')
-        .description('Cancel an active subscription')
+        .description('Cancel an active subscription (prorates remaining period)')
+        .option('--cancel-date-type <type>', 'END_OF_CURRENT_PERIOD, END_OF_LAST_PERIOD, or CUSTOM_DATE', 'END_OF_CURRENT_PERIOD')
+        .option('--end-date <YYYY-MM-DD>', 'Custom cancel date (only with CUSTOM_DATE)')
+        .option('--prorated-text <text>', 'Prorated adjustment line text', 'Prorated adjustment')
         .option('--format <type>', 'Output format: table, json, csv, yaml')
         .option('--api-key <key>', 'API key')
         .option('--json', 'JSON output')
         .action((resourceId, opts) => apiAction(async (client) => {
-        await cancelSubscription(client, resourceId);
+        await cancelSubscription(client, resourceId, {
+            cancelDateType: opts.cancelDateType,
+            proratedAdjustmentLineText: opts.proratedText,
+            endDate: opts.endDate,
+        });
         if (opts.json) {
             console.log(JSON.stringify({ cancelled: true, resourceId }));
             return;

package/dist/core/api/subscriptions.js

@@ -13,8 +13,13 @@ export async function updateSubscription(client, resourceId, data) {
 export async function deleteSubscription(client, resourceId) {
     await client.delete(`/api/v1/scheduled/subscriptions/${resourceId}`);
 }
-export async function cancelSubscription(client, resourceId) {
-    return client.post(`/api/v1/scheduled/cancel-subscriptions/${resourceId}`, {});
+export async function cancelSubscription(client, resourceId, opts) {
+    return client.put(`/api/v1/scheduled/cancel-subscriptions/${resourceId}`, {
+        resourceId,
+        cancelDateType: opts?.cancelDateType ?? 'END_OF_CURRENT_PERIOD',
+        proratedAdjustmentLineText: opts?.proratedAdjustmentLineText ?? 'Prorated adjustment',
+        ...(opts?.endDate ? { endDate: opts.endDate } : {}),
+    });
 }
 export async function searchScheduledTransactions(client, params) {
     // Scheduled transactions sort fields: startDate, nextScheduleDate, etc. (no createdAt)

package/dist/core/registry/tools.js

@@ -3330,10 +3330,14 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
                 accountResourceId,
                 ...(taxProfileResourceId ? { taxProfileResourceId } : {}),
             }));
+            // Subscriptions use repeat + invoice wrapper + proratedConfig (required)
             const body = {
-                businessTransactionType: 'SALE',
-                interval, startDate, contactResourceId, reference, valueDate, dueDate,
-                lineItems: items, saveAsDraft: false, status: 'ACTIVE',
+                repeat: interval, startDate, status: 'ACTIVE',
+                proratedConfig: { proratedAdjustmentLineText: 'Prorated adjustment' },
+                invoice: {
+                    contactResourceId, reference, valueDate, dueDate,
+                    lineItems: items, saveAsDraft: false,
+                },
             };
             if (endDate)
                 body.endDate = endDate;
@@ -3360,14 +3364,19 @@ Use for: software licenses, retainer services, recurring SaaS billing. Invoices
     deleteTool('delete_subscription', 'Delete a subscription. Removes the recurring schedule.', 'subscriptions', (client, id) => deleteSubscription(client, id)),
     {
         name: 'cancel_subscription',
-        description: 'Cancel an active subscription. Stops future billing but preserves history.',
+        description: 'Cancel an active subscription. Prorates remaining period and stops future billing. Must cancel before delete.',
         params: {
             resourceId: { type: 'string', description: 'Subscription resourceId' },
+            cancelDateType: { type: 'string', enum: ['END_OF_CURRENT_PERIOD', 'END_OF_LAST_PERIOD', 'CUSTOM_DATE'], description: 'When to end (default: END_OF_CURRENT_PERIOD)' },
+            endDate: { type: 'string', description: 'Custom cancel date YYYY-MM-DD (only with CUSTOM_DATE)' },
         },
         required: ['resourceId'],
         group: 'subscriptions',
         readOnly: false,
-        execute: async (ctx, input) => cancelSubscription(ctx.client, input.resourceId),
+        execute: async (ctx, input) => cancelSubscription(ctx.client, input.resourceId, {
+            cancelDateType: input.cancelDateType,
+            endDate: input.endDate,
+        }),
     },
     {
         name: 'search_scheduled_transactions',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaz-clio",
-  "version": "4.30.9",
+  "version": "4.30.10",
   "description": "Clio — Command Line Interface Orchestrator for Jaz AI.",
   "type": "module",
   "bin": {