---
title: "Invoices statistics"
method: GET
path: "/statistics/invoices"
tags: ["Statistics"]
---

# Invoices statistics

`GET /statistics/invoices`

Aggregated statistics for the invoices and credit notes Shipmondo has issued to you -- your own spend with the platform.

This is the only statistics resource carrying net, VAT and gross amounts. Only closed documents are included (return-portal documents issued to an end consumer are excluded), so this answers what you have been billed, not what you are currently accruing. Monetary amounts are always expressed in the document's own currency and are never converted; requesting a money metric without restricting or grouping by currency_code groups the response by currency automatically and sets meta.currency_split to true.

Money metrics are marked approximate: see meta.approximate_metrics -- they are aggregated in 32-bit floating point and can differ from the exact decimal figures returned by other endpoints for the same underlying records.

## Query parameters

- `date_from` string, date-time, required
- `date_to` string, date-time, required
- `date_field` 'created_at' | 'updated_at'
- `time_zone` string
- `interval` 'hour' | 'day' | 'week' | 'month'
- `group_by` string
- `metrics` string
- `limit` integer
- `sort` string
- `series_per_group` boolean
- `include_empty_buckets` boolean
- `reference_type` 'shipment' | 'payment_request' | 'payment_requests' | 'generic_payment' | 'generic_payments' | 'sales_header' | 'subscription_period' | 'shipment_case'
- `document_type` 'invoice' | 'credit_note'
- `currency_code` string
- `vat_business_type` 'business' | 'private_person'
- `bill_to_country_code` string
- `vat_percent` string
- `local_currency_code` string

## Response `200`

Successful.

- StatisticsResult
  - `meta` object — The request as it was resolved, including any defaults that were applied.
    - `resource` string
    - `date_field` string
    - `date_from` string, date-time
    - `date_to` string, date-time
    - `time_zone` string
    - `interval` string, nullable
    - `group_by` string[]
    - `metrics` string[]
    - `limit` integer
    - `sort` string — The ordering that was actually applied, in the same form the sort parameter takes.
    - `include_empty_buckets` boolean
    - `series_per_group` boolean
    - `approximate_metrics` string[] — Metrics in this response that are estimates rather than exact counts.
    - `currency_split` boolean — True when the response was grouped by currency automatically because a monetary metric was requested without a single currency scope.
    - `truncated` boolean — True when at least one group level had more distinct values than the requested limit. The remainder is reported in the "other" bucket.
  - `totals` object — The requested metrics across the whole period, before any grouping.
  - `series` object[] — Present when interval was requested.
    - `key` string
    - `metrics` object
  - `groups` StatisticsGroup[] — Present when group_by was requested.
    - `key` string — The grouped value. Enum dimensions return the name rather than an internal number, and boolean dimensions return "true" or "false", so the key can always be fed back into the matching filter. Two reserved keys can appear: "unknown" for records where the dimension is empty, and "other" for everything beyond the requested limit. In the "other" row a metric is null when its residual cannot be derived from the aggregation.
    - `label` string, nullable — Human readable name for the key where one exists, for example a country or customer name. Null when there is nothing to resolve.
    - `metrics` object — The requested metrics for this group. Values are numbers, or null where a metric cannot be computed.
    - `groups` StatisticsGroup[] — Present when a second group_by dimension was requested.
    - `series` object[] — Present on the innermost group when series_per_group was requested. Same shape as the top level series.
      - `key` string
      - `metrics` object

## Other responses

- `401` — Unauthorized.
- `422` — The request was rejected before it reached Elasticsearch. The error_code field identifies the reason, for example date_range_too_large or bucket_budget_exceeded.
- `503` — The query timed out. Narrow the period, reduce group_by, or lower limit.

## Changes

- **2026-09-03** `c787692a7961` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/shipmondo/apis/shipmondo-api/changes/statistics/invoices/get.md)

---

[API](https://skmtc.dev/shipmondo/apis/shipmondo-api.md) · [All operations](https://skmtc.dev/shipmondo/apis/shipmondo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmondo/apis/shipmondo-api/revisions/597a3e53ac0d?raw)