← Invoices APIReturns aggregated totals for invoices in a facility: total quantity, total spend, total CO2e broken down by scope (consumption, generation, T&D), and record count. Supports the same filters as the list endpoint.
Request
Headers
string
required
Your API key for authenticationExample:sk_live_1234567890abcdef
string
required
Your organization UUIDExample:a8315ef3-dd50-43f8-b7ce-d839e68d51fa
Query Parameters
This endpoint accepts the same filters as List Invoices.
uuid
required
UUID of the facility to scope invoices toExample:?facility_id=660e8400-e29b-41d4-a716-446655440000
string
required
Invoice type to retrieveAllowed values:heat, electricity, water, recharge, processExample:?filters=electricity
date
Filter invoices starting on or after this date (YYYY-MM-DD)
date
Filter invoices ending on or before this date (YYYY-MM-DD)
string[]
Filter by invoice statusAllowed values:uploaded, loading, active, inactive, review, error
string
Filter by CO2e calculation statusAllowed values:calculated, not_calculated
string
Partial, case-insensitive match against the invoice numberExample:?invoice_id=INV-2024
string[]
Filter by one or more CUPS codes
UUID[]
Filter by one or more supplier IDs
UUID[]
Filter by one or more facility fuel IDs
UUID[]
Filter by the IDs of users who uploaded the invoice
string[]
Filter by invoice creation sourceKnown values:manual, pdf, bulk_file, datadis
date
Filter invoices uploaded on or after this date (YYYY-MM-DD)
date
Filter invoices uploaded on or before this date (YYYY-MM-DD)
UUID[]
Filter by stationary fuel IDs (natural gas, diesel, biomass). Relevant for heat invoices.
UUID[]
Filter by refrigerant fuel IDs. Relevant for recharge invoices.
UUID[]
Filter by one or more supply contract IDs
string[]
Filter by self-consumption flagAllowed values:true, false
uuid
Filter by project UUID
Response
number
Sum of quantities across all matching invoices
number | null
Sum of monetary amounts (EUR)
number
Total CO2e (tCO2e)
number | null
CO2e from energy consumption (Scope 2 — market/location based)
number | null
CO2e from on-site generation (Scope 1)
number | null
CO2e from transmission and distribution losses (Scope 3)
integer
Number of matching invoices
array[object]
Quantities broken down by unit:
Field
Type
Description
unit_name
string
Unit of measure (e.g. kWh, m³)
total_quantity
number
Sum for this unit
count
integer
Number of invoices with this unit
array[object] | null
Wastes only (null for other types): the emission-factor databases the matching wastes’ management is calculated with, most used first. Versions of one database (e.g. DEFRA 2024 and DEFRA 2026) are grouped.
Field
Type
Description
name
string
Database name
custom
boolean
A database the organization uploaded itself
versions
string[]
Versions in use
count
integer
Wastes calculated with it (once per waste, across years)
array[object] | null
Wastes only (null for other types): the distinct emission factors the matching wastes are calculated with, most used first.