Entity Stats
Entity Stats
Flexible aggregation queries for entity data. Query counts, sums, averages across invoices, payments, customers, and more.
Query entity stats (batch)
/stats/queryExecute one or more aggregation queries on entity data in a single request.
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, 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)
- overdue_bucket - Invoice aging bucket (current, 1-30, 31-60, 61-90, 90+)
Example — single query (monthly revenue):
``json`
[{
"metrics": [{ "type": "sum", "field": "total_with_tax", "alias": "revenue" }],
"table": "invoices",
"date_from": "2024-01-01",
"filters": { "is_draft": false, "voided_at": null },
"group_by": ["month"]
}]
Example — multi query (dashboard counts):json``
[
{ "metrics": [{ "type": "count", "alias": "total" }], "table": "invoices" },
{ "metrics": [{ "type": "count", "alias": "total" }], "table": "customers" }
]
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.entityStats.queryEntityStats([
{
table: "invoices",
metrics: [
{
type: "sum",
field: "financial_gross_converted",
alias: "gross_sales"
},
{
type: "sum",
field: "financial_conversion_missing",
alias: "conversion_missing"
}
],
filters: {
financial_eligible: true
},
date_from: "2024-01-01",
date_to: "2024-12-31",
group_by: [
"month"
],
order_by: [
{
field: "month",
direction: "asc"
}
]
}
], {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);[
{
"query": {
"table": "invoices",
"date_from": "2024-01-01",
"date_to": "2024-12-31",
"group_by": [
"month"
]
},
"data": [
{
"month": "2024-01",
"gross_sales": 5000,
"conversion_missing": 0
}
],
"row_count": 1
}
]