> ## Documentation Index > Fetch the complete documentation index at: https://docs.zivio.com/llms.txt > Use this file to discover all available pages before exploring further. # Aggregate invoice spend grouped by one or more dimensions > Pagination-free spend aggregation computed in SQL. Groups the invoices you are permitted to see by one or more dimensions and (always) currency, returning exact per-currency subtotals plus optional converted roll-ups. Reuses the standard `filter[...]` grammar — including `filter[type]=invoice|credit_note|all` and projects-backed drill-down filters `filter[supplier|category|subcategory|tier3|owner|org]=`. The role-aware measure default and the paid-status default are echoed in `defaults_applied`. Large cross-products are bounded — see `meta` (group_count / returned / truncated). Forbidden or unknown measures/dimensions/filters return 422 (never a silently wrong number). ## OpenAPI ````yaml /api-reference/v4/openapi.json get /invoices/summary openapi: 3.1.0 info: title: API V4 version: '4' description: >- OAuth 2.0 secured API. Obtain an access token using client credentials to access protected endpoints. The regional endpoints listed below serve every Zivio organisation, so each request — including the token request — must carry a `zivio-tenant-id` header identifying yours. Requests without it are rejected with a 404 before any token is checked. contact: name: API Support email: support@zivio.com servers: - url: https://api.zivio.net/api/v4 description: Global API Router - url: https://api.eu.zivio.net/api/v4 description: EU Data Region - url: https://api.uk.zivio.net/api/v4 description: UK Data Region - url: https://api.us.zivio.net/api/v4 description: US Data Region security: - oauth2: [] tenantId: [] paths: /invoices/summary: get: tags: - Invoices summary: Aggregate invoice spend grouped by one or more dimensions description: >- Pagination-free spend aggregation computed in SQL. Groups the invoices you are permitted to see by one or more dimensions and (always) currency, returning exact per-currency subtotals plus optional converted roll-ups. Reuses the standard `filter[...]` grammar — including `filter[type]=invoice|credit_note|all` and projects-backed drill-down filters `filter[supplier|category|subcategory|tier3|owner|org]=`. The role-aware measure default and the paid-status default are echoed in `defaults_applied`. Large cross-products are bounded — see `meta` (group_count / returned / truncated). Forbidden or unknown measures/dimensions/filters return 422 (never a silently wrong number). operationId: getInvoicesSummary parameters: - in: query name: group_by required: true description: >- One or more dimensions, comma-separated (max 4), combined into a composite grouping. Permitted: category, subcategory, tier3, supplier, owner, org, status, month, quarter, year. schema: type: string example: category,supplier - in: query name: measures description: >- Comma-separated measures (defaults per role if omitted): net_total, tax_total, total, sales_net_total, sales_tax_total, sales_total, invoice_count. schema: type: string example: net_total - in: query name: date_dimension description: Date column used for month/quarter/year buckets. schema: type: string enum: - dated_on - paid_at - approved_at - due_on default: dated_on example: dated_on - in: query name: convert_to description: >- Optional ISO currency code for an indicative converted roll-up (per-currency subtotals remain exact). schema: type: string example: GBP - in: query name: filter[] style: deepObject explode: true description: >- Standard filter grammar, e.g. filter[dated_on][gte]=2025-01-01&filter[status]=paid. Also filter[type]=invoice|credit_note|all and projects-backed drill-down filter[supplier]=88 / filter[category]=42 (comma for multiple). schema: type: object - in: query name: cf_project[] style: deepObject explode: true description: >- Filter by the parent Project's tenant-defined custom-field values (cost centre, PO, department, …). Same operator grammar as cf: cf_project[cost_center]=CC-001, cf_project[department][in]=a,b, cf_project[po][exists]=. (cf[...] continues to filter the invoice's own custom fields.) schema: type: object responses: '200': description: Spend summary grouped by the requested dimensions and currency content: application/json: schema: type: object example: summary: resource: invoices group_by: - category - supplier measures: - net_total filters: dated_on: gte: '2025-01-01' lte: '2025-12-31' status: paid defaults_applied: - status currency: mode: converted convert_to: GBP rates_as_of: '2026-06-11' meta: group_count: 1 returned: 1 truncated: false order: net_total desc groups: - dimensions: - key: category id: 42 label: Construction - key: supplier id: 88 label: Acme Build Ltd net_total: amount: '1250000.00' currency: GBP cents: 125000000 share: 100 invoice_count: 87 by_currency: - currency: GBP net_total_cents: 125000000 invoice_count: 87 totals: net_total: amount: '1250000.00' currency: GBP cents: 125000000 invoice_count: 87 '401': description: >- Unauthorized - the access token is missing, expired, revoked or malformed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_token error_description: >- The access token provided is expired, revoked, malformed, or invalid for other reasons '403': description: Forbidden - insufficient scope content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient_scope error_description: >- The request requires higher privileges than provided by the access token required_scope: invoices:read provided_scopes: - welcome:read '422': description: Unknown or forbidden measure, dimension, filter, or currency content: application/json: schema: type: object example: error: measure 'net_total' is not permitted security: - oauth2: - invoices:read tenantId: [] components: schemas: Error: type: object description: Error envelope returned by every non-2xx V4 response properties: error: type: string example: insufficient_scope error_description: type: string message: type: string details: type: object additionalProperties: true required_scope: type: string example: projects:read provided_scopes: type: array items: type: string securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client credentials. The access token from POST /oauth/token is sent as a bearer token. Request only the scopes you need. flows: clientCredentials: tokenUrl: https://api.zivio.net/api/v4/oauth/token scopes: bank_accounts:read: Read bank account details on suppliers and the org. catalogs:read: Read catalog items. cost_centers:read: Read cost center records. eoi_responses:read: Read responses to expressions of interest. eois:read: Read expressions of interest. offers:read: Read offers for projects. org_units:read: Read your organization unit hierarchy. org_users:read: Read members of your organization. resources:read: Read resource (worker) records. sales_invoices:read: Read invoices issued to clients. sales_milestones:read: Read milestones on sales engagements. skill_categories:read: Read the skill category taxonomy. skill_taxonomies:read: Read skill taxonomy structure. skills:read: Read individual skills. supplier_documents:read: Read documents uploaded by suppliers. supplier_lists:read: Read curated lists of suppliers. supplier_users:read: Read users belonging to supplier organizations. tax_types:read: Read configured tax types. users:read: Read user profiles. variation_orders:read: Read variation orders on projects. welcome:read: 'Required: confirms your identity to the application.' bid_evaluations:read: >- Read evaluation scorecards for bids, including criterion scores and quality, cost and total scores. bid_evaluations:write: >- Score bids against a project's quality criteria and override calculated cost scores. bids:read: Read bids submitted on projects. bids:write: >- Shortlist, select, eliminate and reinstate bids submitted on projects. invoices:read: Read invoices on projects. invoices:write: Create and update invoices. notes:read: Read notes on projects and EOIs. notes:write: Create and update notes on projects and EOIs. project_approvals:read: Read project approval workflows. project_approvals:write: Create and update project approval workflows. project_conversations:read: Read messages exchanged with suppliers on a project. project_conversations:write: Send messages to suppliers on a project. project_invitations:read: Read supplier invitations on projects. project_invitations:write: Invite suppliers to bid on projects. project_questions:read: Read supplier clarification questions on projects. project_questions:write: Answer and approve supplier clarification questions. projects:read: Read projects. projects:write: Create and update projects. milestones:read: Read milestones on projects. milestones:write: Create and update milestones. orgs:read: Read organization records. orgs:write: Create and update organization records. purchase_orders:read: Read purchase orders. purchase_orders:write: Create and update purchase orders. reviews:read: Read reviews left on suppliers. reviews:write: Create and update reviews. suppliers:read: Read supplier profiles. suppliers:write: Create and update supplier profiles. raw_scorecard_entries:write: Create and update raw scorecard entries. raw_scorecard_entries:read: Read raw scorecard entries. tasks:read: >- Read the acting user's task queue, including outstanding approvals and items to review. tasks:write: Complete and dismiss tasks in the acting user's task queue. act_as_user: >- Make requests as another user within the token holder's delegation boundary. tenantId: type: apiKey name: zivio-tenant-id in: header description: >- Your Zivio organisation identifier. The regional API endpoints serve every Zivio organisation, so each request must identify yours. ````