@spaceinvoices/js-sdk 8.1.0 → 8.2.0

package/dist/generated/entity-stats/entity-stats.d.cts

@@ -9,12 +9,24 @@ import type { Error, StatsQueryBatchRequest, StatsQueryBatchResponse, Validation
 /**
  * Execute one or more aggregation queries on entity data in a single request.
 
-Send an array of 1-25 queries. Each query runs independently and results are returned in the same order.
+Send an array of 1-25 queries. Queries share one read-only database snapshot and results are returned in the same order.
 
-**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items
+**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items, invoice_taxes, credit_note_taxes
 
 **Metric types**: count, sum, avg, min, max
 
+**Filters and results**: filters accept a scalar, null, or an object containing only `not` with a scalar or null value. Unsupported operators, arrays, nested objects, duplicate result names, and the reserved alias `__proto__` return HTTP 400. Metric aliases must not collide with grouping fields. Text dimensions, including numeric-looking customer names and year strings, remain strings; numeric metrics are numbers.
+
+**Financial reporting**:
+- Invoice and credit-note queries can filter `financial_eligible: true` to exclude drafts, voided/deleted documents and cancellation credits whose original invoices are already excluded. Raw fields retain their existing meaning.
+- Sum `financial_gross_converted` for gross invoice-date sales in the entity currency; subtract the equivalent eligible credit-note sum for net sales after credits. This is tax-inclusive sales, not service-period revenue recognition. Invoice `total_due_converted` reports invoice-only outstanding balances.
+- Sum `collection_amount_converted` for direct invoice cash receipts or positive credit-note refund magnitudes, capped per document. Applied credits and advance allocations are excluded. Include `collection_conversion_missing` to detect unusable cash conversions as well as missing document conversion. Subtract refunds from invoice collections, and eligible credits from invoiced gross; bound collected cash to zero through net invoiced gross before calculating the rate. A nonpositive denominator has a zero rate.
+- Payment charts use `active_invoice_cash_receipt: true` and `cash_amount_converted`. These are receipts on active invoices, excluding supplier payments, refunds and noncash allocations.
+- On `invoice_taxes` and `credit_note_taxes`, use `financial_eligible: true` and `reverse_charge: false`, sum `tax_converted` by `rate`, then subtract eligible credit-note tax. This measures tax charged by document date, not cash tax collections or tax liability after expenses. `base_converted` provides the corresponding taxable base.
+- Include a sum of `financial_conversion_missing` in every financial query. A positive result means the aggregate is incomplete and must be shown as unavailable, rather than treating omitted conversion values as zero. For limited rankings, check missing conversions across the whole eligible population in a separate query before presenting the ranking. Historical copied foreign amounts without conversion evidence are not treated as valid 1:1 conversions.
+- Group invoice sales by `customer_key` and `customer_display_name` to keep linked customers stable across name changes; unlinked snapshots use a normalized-name fallback.
+- Date filters are inclusive calendar dates. Invoice overdue fields use the entity timezone; callers should construct reporting periods in that same timezone.
+
 **Virtual fields for group_by**:
 - `month` - Extract month from date (YYYY-MM)
 - `year` - Extract year from date (YYYY)

package/dist/generated/entity-stats/entity-stats.d.ts

@@ -9,12 +9,24 @@ import type { Error, StatsQueryBatchRequest, StatsQueryBatchResponse, Validation
 /**
  * Execute one or more aggregation queries on entity data in a single request.
 
-Send an array of 1-25 queries. Each query runs independently and results are returned in the same order.
+Send an array of 1-25 queries. Queries share one read-only database snapshot and results are returned in the same order.
 
-**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items
+**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items, invoice_taxes, credit_note_taxes
 
 **Metric types**: count, sum, avg, min, max
 
+**Filters and results**: filters accept a scalar, null, or an object containing only `not` with a scalar or null value. Unsupported operators, arrays, nested objects, duplicate result names, and the reserved alias `__proto__` return HTTP 400. Metric aliases must not collide with grouping fields. Text dimensions, including numeric-looking customer names and year strings, remain strings; numeric metrics are numbers.
+
+**Financial reporting**:
+- Invoice and credit-note queries can filter `financial_eligible: true` to exclude drafts, voided/deleted documents and cancellation credits whose original invoices are already excluded. Raw fields retain their existing meaning.
+- Sum `financial_gross_converted` for gross invoice-date sales in the entity currency; subtract the equivalent eligible credit-note sum for net sales after credits. This is tax-inclusive sales, not service-period revenue recognition. Invoice `total_due_converted` reports invoice-only outstanding balances.
+- Sum `collection_amount_converted` for direct invoice cash receipts or positive credit-note refund magnitudes, capped per document. Applied credits and advance allocations are excluded. Include `collection_conversion_missing` to detect unusable cash conversions as well as missing document conversion. Subtract refunds from invoice collections, and eligible credits from invoiced gross; bound collected cash to zero through net invoiced gross before calculating the rate. A nonpositive denominator has a zero rate.
+- Payment charts use `active_invoice_cash_receipt: true` and `cash_amount_converted`. These are receipts on active invoices, excluding supplier payments, refunds and noncash allocations.
+- On `invoice_taxes` and `credit_note_taxes`, use `financial_eligible: true` and `reverse_charge: false`, sum `tax_converted` by `rate`, then subtract eligible credit-note tax. This measures tax charged by document date, not cash tax collections or tax liability after expenses. `base_converted` provides the corresponding taxable base.
+- Include a sum of `financial_conversion_missing` in every financial query. A positive result means the aggregate is incomplete and must be shown as unavailable, rather than treating omitted conversion values as zero. For limited rankings, check missing conversions across the whole eligible population in a separate query before presenting the ranking. Historical copied foreign amounts without conversion evidence are not treated as valid 1:1 conversions.
+- Group invoice sales by `customer_key` and `customer_display_name` to keep linked customers stable across name changes; unlinked snapshots use a normalized-name fallback.
+- Date filters are inclusive calendar dates. Invoice overdue fields use the entity timezone; callers should construct reporting periods in that same timezone.
+
 **Virtual fields for group_by**:
 - `month` - Extract month from date (YYYY-MM)
 - `year` - Extract year from date (YYYY)

package/dist/generated/expenses/expenses.d.cts

@@ -339,6 +339,8 @@ export declare const backfillExpenseRecognition: (expenseRecognitionBackfill: Ex
 
 Returns **202 Accepted** with the job, expense, and file identifiers. Recognition is asynchronous in live mode; poll `GET /expenses/recognitions/{id}` for status. Terminal success is `ready_for_review` or `needs_attention`; terminal failure is `failed`, with safe `error_code` and `error_message` fields.
 
+Parsed document and line amounts are checked against the standard expense calculation before applying extraction. A disagreement keeps the draft unchanged and stores the extraction with `needs_attention` for review.
+
 Payment suggestions from OCR are advisory only and never mark the expense paid or create payments. Failed provider attempts record zero customer usage. Automatic provider attempts and a permitted customer retry share the same job; billable customer usage is recorded once only after a successful terminal result.
 
 `X-Request-Id` provides account/entity-scoped replay and fails closed with 409 Conflict when reused for different file content.

package/dist/generated/expenses/expenses.d.ts

@@ -339,6 +339,8 @@ export declare const backfillExpenseRecognition: (expenseRecognitionBackfill: Ex
 
 Returns **202 Accepted** with the job, expense, and file identifiers. Recognition is asynchronous in live mode; poll `GET /expenses/recognitions/{id}` for status. Terminal success is `ready_for_review` or `needs_attention`; terminal failure is `failed`, with safe `error_code` and `error_message` fields.
 
+Parsed document and line amounts are checked against the standard expense calculation before applying extraction. A disagreement keeps the draft unchanged and stores the extraction with `needs_attention` for review.
+
 Payment suggestions from OCR are advisory only and never mark the expense paid or create payments. Failed provider attempts record zero customer usage. Automatic provider attempts and a permitted customer retry share the same job; billable customer usage is recorded once only after a successful terminal result.
 
 `X-Request-Id` provides account/entity-scoped replay and fails closed with 409 Conflict when reused for different file content.

package/dist/generated/financial-categories/financial-categories.d.cts

@@ -185,6 +185,10 @@ export type getRevenueByFinancialCategoryResponse404 = {
     data: Error;
     status: 404;
 };
+export type getRevenueByFinancialCategoryResponse422 = {
+    data: Error;
+    status: 422;
+};
 export type getRevenueByFinancialCategoryResponse500 = {
     data: Error;
     status: 500;
@@ -192,7 +196,7 @@ export type getRevenueByFinancialCategoryResponse500 = {
 export type getRevenueByFinancialCategoryResponseSuccess = (getRevenueByFinancialCategoryResponse200) & {
     headers: Headers;
 };
-export type getRevenueByFinancialCategoryResponseError = (getRevenueByFinancialCategoryResponse400 | getRevenueByFinancialCategoryResponse401 | getRevenueByFinancialCategoryResponse403 | getRevenueByFinancialCategoryResponse404 | getRevenueByFinancialCategoryResponse500) & {
+export type getRevenueByFinancialCategoryResponseError = (getRevenueByFinancialCategoryResponse400 | getRevenueByFinancialCategoryResponse401 | getRevenueByFinancialCategoryResponse403 | getRevenueByFinancialCategoryResponse404 | getRevenueByFinancialCategoryResponse422 | getRevenueByFinancialCategoryResponse500) & {
     headers: Headers;
 };
 export type getRevenueByFinancialCategoryResponse = (getRevenueByFinancialCategoryResponseSuccess | getRevenueByFinancialCategoryResponseError);

package/dist/generated/financial-categories/financial-categories.d.ts

@@ -185,6 +185,10 @@ export type getRevenueByFinancialCategoryResponse404 = {
     data: Error;
     status: 404;
 };
+export type getRevenueByFinancialCategoryResponse422 = {
+    data: Error;
+    status: 422;
+};
 export type getRevenueByFinancialCategoryResponse500 = {
     data: Error;
     status: 500;
@@ -192,7 +196,7 @@ export type getRevenueByFinancialCategoryResponse500 = {
 export type getRevenueByFinancialCategoryResponseSuccess = (getRevenueByFinancialCategoryResponse200) & {
     headers: Headers;
 };
-export type getRevenueByFinancialCategoryResponseError = (getRevenueByFinancialCategoryResponse400 | getRevenueByFinancialCategoryResponse401 | getRevenueByFinancialCategoryResponse403 | getRevenueByFinancialCategoryResponse404 | getRevenueByFinancialCategoryResponse500) & {
+export type getRevenueByFinancialCategoryResponseError = (getRevenueByFinancialCategoryResponse400 | getRevenueByFinancialCategoryResponse401 | getRevenueByFinancialCategoryResponse403 | getRevenueByFinancialCategoryResponse404 | getRevenueByFinancialCategoryResponse422 | getRevenueByFinancialCategoryResponse500) & {
     headers: Headers;
 };
 export type getRevenueByFinancialCategoryResponse = (getRevenueByFinancialCategoryResponseSuccess | getRevenueByFinancialCategoryResponseError);

package/dist/generated/model/getInvoicesParams.d.cts

@@ -46,7 +46,7 @@ export type GetInvoicesParams = {
     - `endsWith` - String ends with
     - `between` - Value between two numbers/dates [min, max]
     
-    **Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, date_due, paid_in_full, total_due, total_paid, voided_at
+    **Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, is_draft, date_due, paid_in_full, total_due, total_paid, voided_at
     
     **Examples:**
     - `{"total": {"gte": 1000}}` - Invoices over 1000

package/dist/generated/model/getInvoicesParams.d.ts

@@ -46,7 +46,7 @@ export type GetInvoicesParams = {
     - `endsWith` - String ends with
     - `between` - Value between two numbers/dates [min, max]
     
-    **Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, date_due, paid_in_full, total_due, total_paid, voided_at
+    **Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, is_draft, date_due, paid_in_full, total_due, total_paid, voided_at
     
     **Examples:**
     - `{"total": {"gte": 1000}}` - Invoices over 1000

package/dist/generated/model/statsQueryRequestTable.d.cts

@@ -18,4 +18,5 @@ export declare const StatsQueryRequestTable: {
     readonly customers: "customers";
     readonly items: "items";
     readonly invoice_taxes: "invoice_taxes";
+    readonly credit_note_taxes: "credit_note_taxes";
 };

package/dist/generated/model/statsQueryRequestTable.d.ts

@@ -18,4 +18,5 @@ export declare const StatsQueryRequestTable: {
     readonly customers: "customers";
     readonly items: "items";
     readonly invoice_taxes: "invoice_taxes";
+    readonly credit_note_taxes: "credit_note_taxes";
 };

package/dist/generated/revenue-recognition/revenue-recognition.d.cts

@@ -145,6 +145,10 @@ export type getRevenueRecognitionReportResponse404 = {
     data: Error;
     status: 404;
 };
+export type getRevenueRecognitionReportResponse422 = {
+    data: Error;
+    status: 422;
+};
 export type getRevenueRecognitionReportResponse500 = {
     data: Error;
     status: 500;
@@ -152,7 +156,7 @@ export type getRevenueRecognitionReportResponse500 = {
 export type getRevenueRecognitionReportResponseSuccess = (getRevenueRecognitionReportResponse200) & {
     headers: Headers;
 };
-export type getRevenueRecognitionReportResponseError = (getRevenueRecognitionReportResponse400 | getRevenueRecognitionReportResponse401 | getRevenueRecognitionReportResponse403 | getRevenueRecognitionReportResponse404 | getRevenueRecognitionReportResponse500) & {
+export type getRevenueRecognitionReportResponseError = (getRevenueRecognitionReportResponse400 | getRevenueRecognitionReportResponse401 | getRevenueRecognitionReportResponse403 | getRevenueRecognitionReportResponse404 | getRevenueRecognitionReportResponse422 | getRevenueRecognitionReportResponse500) & {
     headers: Headers;
 };
 export type getRevenueRecognitionReportResponse = (getRevenueRecognitionReportResponseSuccess | getRevenueRecognitionReportResponseError);
@@ -181,6 +185,10 @@ export type getRevenueRecognitionDetailsResponse404 = {
     data: Error;
     status: 404;
 };
+export type getRevenueRecognitionDetailsResponse422 = {
+    data: Error;
+    status: 422;
+};
 export type getRevenueRecognitionDetailsResponse500 = {
     data: Error;
     status: 500;
@@ -188,7 +196,7 @@ export type getRevenueRecognitionDetailsResponse500 = {
 export type getRevenueRecognitionDetailsResponseSuccess = (getRevenueRecognitionDetailsResponse200) & {
     headers: Headers;
 };
-export type getRevenueRecognitionDetailsResponseError = (getRevenueRecognitionDetailsResponse400 | getRevenueRecognitionDetailsResponse401 | getRevenueRecognitionDetailsResponse403 | getRevenueRecognitionDetailsResponse404 | getRevenueRecognitionDetailsResponse500) & {
+export type getRevenueRecognitionDetailsResponseError = (getRevenueRecognitionDetailsResponse400 | getRevenueRecognitionDetailsResponse401 | getRevenueRecognitionDetailsResponse403 | getRevenueRecognitionDetailsResponse404 | getRevenueRecognitionDetailsResponse422 | getRevenueRecognitionDetailsResponse500) & {
     headers: Headers;
 };
 export type getRevenueRecognitionDetailsResponse = (getRevenueRecognitionDetailsResponseSuccess | getRevenueRecognitionDetailsResponseError);

package/dist/generated/revenue-recognition/revenue-recognition.d.ts

@@ -145,6 +145,10 @@ export type getRevenueRecognitionReportResponse404 = {
     data: Error;
     status: 404;
 };
+export type getRevenueRecognitionReportResponse422 = {
+    data: Error;
+    status: 422;
+};
 export type getRevenueRecognitionReportResponse500 = {
     data: Error;
     status: 500;
@@ -152,7 +156,7 @@ export type getRevenueRecognitionReportResponse500 = {
 export type getRevenueRecognitionReportResponseSuccess = (getRevenueRecognitionReportResponse200) & {
     headers: Headers;
 };
-export type getRevenueRecognitionReportResponseError = (getRevenueRecognitionReportResponse400 | getRevenueRecognitionReportResponse401 | getRevenueRecognitionReportResponse403 | getRevenueRecognitionReportResponse404 | getRevenueRecognitionReportResponse500) & {
+export type getRevenueRecognitionReportResponseError = (getRevenueRecognitionReportResponse400 | getRevenueRecognitionReportResponse401 | getRevenueRecognitionReportResponse403 | getRevenueRecognitionReportResponse404 | getRevenueRecognitionReportResponse422 | getRevenueRecognitionReportResponse500) & {
     headers: Headers;
 };
 export type getRevenueRecognitionReportResponse = (getRevenueRecognitionReportResponseSuccess | getRevenueRecognitionReportResponseError);
@@ -181,6 +185,10 @@ export type getRevenueRecognitionDetailsResponse404 = {
     data: Error;
     status: 404;
 };
+export type getRevenueRecognitionDetailsResponse422 = {
+    data: Error;
+    status: 422;
+};
 export type getRevenueRecognitionDetailsResponse500 = {
     data: Error;
     status: 500;
@@ -188,7 +196,7 @@ export type getRevenueRecognitionDetailsResponse500 = {
 export type getRevenueRecognitionDetailsResponseSuccess = (getRevenueRecognitionDetailsResponse200) & {
     headers: Headers;
 };
-export type getRevenueRecognitionDetailsResponseError = (getRevenueRecognitionDetailsResponse400 | getRevenueRecognitionDetailsResponse401 | getRevenueRecognitionDetailsResponse403 | getRevenueRecognitionDetailsResponse404 | getRevenueRecognitionDetailsResponse500) & {
+export type getRevenueRecognitionDetailsResponseError = (getRevenueRecognitionDetailsResponse400 | getRevenueRecognitionDetailsResponse401 | getRevenueRecognitionDetailsResponse403 | getRevenueRecognitionDetailsResponse404 | getRevenueRecognitionDetailsResponse422 | getRevenueRecognitionDetailsResponse500) & {
     headers: Headers;
 };
 export type getRevenueRecognitionDetailsResponse = (getRevenueRecognitionDetailsResponseSuccess | getRevenueRecognitionDetailsResponseError);

package/dist/generated-zod/entity-stats/entity-stats.d.cts

@@ -9,12 +9,24 @@ import * as zod from "zod";
 /**
  * Execute one or more aggregation queries on entity data in a single request.
 
-Send an array of 1-25 queries. Each query runs independently and results are returned in the same order.
+Send an array of 1-25 queries. Queries share one read-only database snapshot and results are returned in the same order.
 
-**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items
+**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items, invoice_taxes, credit_note_taxes
 
 **Metric types**: count, sum, avg, min, max
 
+**Filters and results**: filters accept a scalar, null, or an object containing only `not` with a scalar or null value. Unsupported operators, arrays, nested objects, duplicate result names, and the reserved alias `__proto__` return HTTP 400. Metric aliases must not collide with grouping fields. Text dimensions, including numeric-looking customer names and year strings, remain strings; numeric metrics are numbers.
+
+**Financial reporting**:
+- Invoice and credit-note queries can filter `financial_eligible: true` to exclude drafts, voided/deleted documents and cancellation credits whose original invoices are already excluded. Raw fields retain their existing meaning.
+- Sum `financial_gross_converted` for gross invoice-date sales in the entity currency; subtract the equivalent eligible credit-note sum for net sales after credits. This is tax-inclusive sales, not service-period revenue recognition. Invoice `total_due_converted` reports invoice-only outstanding balances.
+- Sum `collection_amount_converted` for direct invoice cash receipts or positive credit-note refund magnitudes, capped per document. Applied credits and advance allocations are excluded. Include `collection_conversion_missing` to detect unusable cash conversions as well as missing document conversion. Subtract refunds from invoice collections, and eligible credits from invoiced gross; bound collected cash to zero through net invoiced gross before calculating the rate. A nonpositive denominator has a zero rate.
+- Payment charts use `active_invoice_cash_receipt: true` and `cash_amount_converted`. These are receipts on active invoices, excluding supplier payments, refunds and noncash allocations.
+- On `invoice_taxes` and `credit_note_taxes`, use `financial_eligible: true` and `reverse_charge: false`, sum `tax_converted` by `rate`, then subtract eligible credit-note tax. This measures tax charged by document date, not cash tax collections or tax liability after expenses. `base_converted` provides the corresponding taxable base.
+- Include a sum of `financial_conversion_missing` in every financial query. A positive result means the aggregate is incomplete and must be shown as unavailable, rather than treating omitted conversion values as zero. For limited rankings, check missing conversions across the whole eligible population in a separate query before presenting the ranking. Historical copied foreign amounts without conversion evidence are not treated as valid 1:1 conversions.
+- Group invoice sales by `customer_key` and `customer_display_name` to keep linked customers stable across name changes; unlinked snapshots use a normalized-name fallback.
+- Date filters are inclusive calendar dates. Invoice overdue fields use the entity timezone; callers should construct reporting periods in that same timezone.
+
 **Virtual fields for group_by**:
 - `month` - Extract month from date (YYYY-MM)
 - `year` - Extract year from date (YYYY)
@@ -69,6 +81,7 @@ export declare const QueryEntityStatsBodyItem: zod.ZodObject<{
         customers: "customers";
         items: "items";
         invoice_taxes: "invoice_taxes";
+        credit_note_taxes: "credit_note_taxes";
     }>;
     date_from: zod.ZodOptional<zod.ZodString>;
     date_to: zod.ZodOptional<zod.ZodString>;
@@ -104,6 +117,7 @@ export declare const QueryEntityStatsBody: zod.ZodArray<zod.ZodObject<{
         customers: "customers";
         items: "items";
         invoice_taxes: "invoice_taxes";
+        credit_note_taxes: "credit_note_taxes";
     }>;
     date_from: zod.ZodOptional<zod.ZodString>;
     date_to: zod.ZodOptional<zod.ZodString>;

package/dist/generated-zod/entity-stats/entity-stats.d.ts

@@ -9,12 +9,24 @@ import * as zod from "zod";
 /**
  * Execute one or more aggregation queries on entity data in a single request.
 
-Send an array of 1-25 queries. Each query runs independently and results are returned in the same order.
+Send an array of 1-25 queries. Queries share one read-only database snapshot and results are returned in the same order.
 
-**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items
+**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items, invoice_taxes, credit_note_taxes
 
 **Metric types**: count, sum, avg, min, max
 
+**Filters and results**: filters accept a scalar, null, or an object containing only `not` with a scalar or null value. Unsupported operators, arrays, nested objects, duplicate result names, and the reserved alias `__proto__` return HTTP 400. Metric aliases must not collide with grouping fields. Text dimensions, including numeric-looking customer names and year strings, remain strings; numeric metrics are numbers.
+
+**Financial reporting**:
+- Invoice and credit-note queries can filter `financial_eligible: true` to exclude drafts, voided/deleted documents and cancellation credits whose original invoices are already excluded. Raw fields retain their existing meaning.
+- Sum `financial_gross_converted` for gross invoice-date sales in the entity currency; subtract the equivalent eligible credit-note sum for net sales after credits. This is tax-inclusive sales, not service-period revenue recognition. Invoice `total_due_converted` reports invoice-only outstanding balances.
+- Sum `collection_amount_converted` for direct invoice cash receipts or positive credit-note refund magnitudes, capped per document. Applied credits and advance allocations are excluded. Include `collection_conversion_missing` to detect unusable cash conversions as well as missing document conversion. Subtract refunds from invoice collections, and eligible credits from invoiced gross; bound collected cash to zero through net invoiced gross before calculating the rate. A nonpositive denominator has a zero rate.
+- Payment charts use `active_invoice_cash_receipt: true` and `cash_amount_converted`. These are receipts on active invoices, excluding supplier payments, refunds and noncash allocations.
+- On `invoice_taxes` and `credit_note_taxes`, use `financial_eligible: true` and `reverse_charge: false`, sum `tax_converted` by `rate`, then subtract eligible credit-note tax. This measures tax charged by document date, not cash tax collections or tax liability after expenses. `base_converted` provides the corresponding taxable base.
+- Include a sum of `financial_conversion_missing` in every financial query. A positive result means the aggregate is incomplete and must be shown as unavailable, rather than treating omitted conversion values as zero. For limited rankings, check missing conversions across the whole eligible population in a separate query before presenting the ranking. Historical copied foreign amounts without conversion evidence are not treated as valid 1:1 conversions.
+- Group invoice sales by `customer_key` and `customer_display_name` to keep linked customers stable across name changes; unlinked snapshots use a normalized-name fallback.
+- Date filters are inclusive calendar dates. Invoice overdue fields use the entity timezone; callers should construct reporting periods in that same timezone.
+
 **Virtual fields for group_by**:
 - `month` - Extract month from date (YYYY-MM)
 - `year` - Extract year from date (YYYY)
@@ -69,6 +81,7 @@ export declare const QueryEntityStatsBodyItem: zod.ZodObject<{
         customers: "customers";
         items: "items";
         invoice_taxes: "invoice_taxes";
+        credit_note_taxes: "credit_note_taxes";
     }>;
     date_from: zod.ZodOptional<zod.ZodString>;
     date_to: zod.ZodOptional<zod.ZodString>;
@@ -104,6 +117,7 @@ export declare const QueryEntityStatsBody: zod.ZodArray<zod.ZodObject<{
         customers: "customers";
         items: "items";
         invoice_taxes: "invoice_taxes";
+        credit_note_taxes: "credit_note_taxes";
     }>;
     date_from: zod.ZodOptional<zod.ZodString>;
     date_to: zod.ZodOptional<zod.ZodString>;

package/dist/generated-zod/expenses/expenses.d.cts

@@ -955,6 +955,8 @@ export declare const BackfillExpenseRecognitionResponse: zod.ZodObject<{
 
 Returns **202 Accepted** with the job, expense, and file identifiers. Recognition is asynchronous in live mode; poll `GET /expenses/recognitions/{id}` for status. Terminal success is `ready_for_review` or `needs_attention`; terminal failure is `failed`, with safe `error_code` and `error_message` fields.
 
+Parsed document and line amounts are checked against the standard expense calculation before applying extraction. A disagreement keeps the draft unchanged and stores the extraction with `needs_attention` for review.
+
 Payment suggestions from OCR are advisory only and never mark the expense paid or create payments. Failed provider attempts record zero customer usage. Automatic provider attempts and a permitted customer retry share the same job; billable customer usage is recorded once only after a successful terminal result.
 
 `X-Request-Id` provides account/entity-scoped replay and fails closed with 409 Conflict when reused for different file content.

package/dist/generated-zod/expenses/expenses.d.ts

@@ -955,6 +955,8 @@ export declare const BackfillExpenseRecognitionResponse: zod.ZodObject<{
 
 Returns **202 Accepted** with the job, expense, and file identifiers. Recognition is asynchronous in live mode; poll `GET /expenses/recognitions/{id}` for status. Terminal success is `ready_for_review` or `needs_attention`; terminal failure is `failed`, with safe `error_code` and `error_message` fields.
 
+Parsed document and line amounts are checked against the standard expense calculation before applying extraction. A disagreement keeps the draft unchanged and stores the extraction with `needs_attention` for review.
+
 Payment suggestions from OCR are advisory only and never mark the expense paid or create payments. Failed provider attempts record zero customer usage. Automatic provider attempts and a permitted customer retry share the same job; billable customer usage is recorded once only after a successful terminal result.
 
 `X-Request-Id` provides account/entity-scoped replay and fails closed with 409 Conflict when reused for different file content.