Invoice Tools

Query energy invoices — electricity, gas, water, diesel, and other consumption records linked to a facility. Each invoice has quantity, dates, and CO₂e emissions. This covers Scope 1 (stationary combustion) and Scope 2 (purchased energy) data.

Both facility_id and invoice_type are required. Call list_facilities first to discover facility IDs, then query invoices by type.

`list_invoices`

List energy invoices for a specific facility filtered by type. Parameters:

Parameter	Type	Required	Default	Description
`facility_id`	string	Yes	—	UUID of the facility
`invoice_type`	string	Yes	—	Invoice type (see below)
`organization_id`	string	No	default org	Organization UUID
`status`	string	No	—	Status filter: `active`, `deleted`
`start_date`	string	No	—	Filter from this date (YYYY-MM-DD)
`end_date`	string	No	—	Filter until this date (YYYY-MM-DD)
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page (max 100)

Invoice Types

Value	Scope	Description
`electricity`	Scope 2	Electricity consumption
`natural_gas`	Scope 1	Natural gas
`diesel`	Scope 1	Diesel fuel
`water`	—	Water consumption
`heat`	Scope 2	District heating
`recharge`	Scope 1	Electric vehicle recharging
`process`	Scope 1	Industrial process fuels

Example response:

{
  "items": [
    {
      "id": "b46d1f0a-...",
      "type": "electricity",
      "status": "active",
      "quantity": 3060.8,
      "co2e": 1347.0,
      "start_date": "2025-06-30T00:00:00",
      "end_date": "2025-07-31T00:00:00",
      "facility_id": "4cc2ac22-...",
      "cups": "ES0022000006089269MY1P"
    }
  ],
  "total": 625,
  "page": 1,
  "size": 50,
  "pages": 13
}

Key response fields:

Field	Description
`type`	Invoice type (matches the `invoice_type` filter)
`quantity`	Consumption amount (kWh for electricity, m³ for gas/water, etc.)
`co2e`	Calculated CO₂e emissions in kg
`start_date` / `end_date`	Billing period
`cups`	CUPS supply point code (Spanish energy market identifier)

Example prompts:

"List electricity invoices for our Madrid office"
"Show gas invoices from last quarter"
"What's our water consumption at facility abc-123?"
"Show diesel invoices for 2024"
"Which invoices have the highest CO₂ emissions?"

`create_invoice`

Create a new energy invoice for a facility. The invoice is allocated 100% to the specified facility. Parameters:

Parameter	Type	Required	Description
`invoice_type`	string	Yes	Invoice type: `heat`, `electricity`, `water`, `recharge`, or `process`
`base_quantity`	number	Yes	Consumption quantity (must be >= 0)
`unit_id`	string	Yes	UUID of the measurement unit (e.g. kWh, m³)
`facility_id`	string	Yes	UUID of the facility
`start_date`	string	Yes	Invoice period start date (YYYY-MM-DD)
`end_date`	string	Yes	Invoice period end date (YYYY-MM-DD)
`supplier_id`	string	No	UUID of the energy supplier
`stationary_fuel_id`	string	No	UUID of the stationary fuel type (for heat/process)
`refrigerant_fuel_id`	string	No	UUID of the refrigerant fuel type
`custom_emission_factor_id`	string	No	UUID of a custom emission factor
`invoice_number`	string	No	External invoice number or identifier
`cups`	string	No	CUPS code (electricity supply point, Spain)
`base_total_spend`	number	No	Total monetary amount
`currency_unit_id`	string	No	UUID of the currency unit
`self_consumption`	boolean	No	Self-consumed electricity (only for electricity type)
`organization_id`	string	No	Organization UUID (uses default if not set)

Example prompts:

"Create an electricity invoice for 3000 kWh at our Madrid facility for January 2025"
"Add a gas invoice for facility abc-123 with 500 m³ consumption"

`update_invoice`

Update an existing invoice. Only provided fields are changed (partial update). Parameters:

Parameter	Type	Required	Description
`invoice_id`	string	Yes	UUID of the invoice to update
`facility_id`	string	No	New facility UUID
`supplier_id`	string	No	New supplier UUID
`status`	string	No	New status: `uploaded`, `loading`, `active`, `inactive`, `review`, or `error`
`invoice_number`	string	No	New external invoice number
`cups`	string	No	New CUPS code
`enabled`	boolean	No	Whether the invoice is enabled for calculations
`self_consumption`	boolean	No	Whether this is self-consumed electricity
`organization_id`	string	No	Organization UUID (uses default if not set)

Example prompts:

"Set invoice b46d1f0a-... to inactive"
"Disable invoice calculations for invoice abc-123"
"Change the supplier for our latest electricity invoice"

Workflow

Find facilities — list_facilities to discover facility IDs
List invoices by type — list_invoices with facility_id and invoice_type
Create invoices — create_invoice to add new consumption records
Update invoices — update_invoice to change status, supplier, or toggle calculations
View emissions — get_greenhouse_gas_emissions with category=electricity (or stationary, etc.) for aggregated totals

API: List Invoices

REST API equivalent with additional filters

Facilities

Find facility IDs to query invoices

Emissions

Aggregated Scope 1 & 2 emissions

CLI

Manage invoices from the command line

Getting Started

Tools Reference

Reference Data

Invoice Tools

Invoice Tools

`list_invoices`

Invoice Types

`create_invoice`

`update_invoice`

Workflow

API: List Invoices

Facilities

Emissions

CLI

​Invoice Tools

​list_invoices

​Invoice Types

​create_invoice

​update_invoice

​Workflow

​Related

API: List Invoices

Facilities

Emissions

CLI

Invoice Tools

`list_invoices`

Invoice Types

`create_invoice`

`update_invoice`

Workflow

Related