Totals - Dcycle Platform Docs

Totals

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/invoices/totals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/invoices/totals"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "total_quantity": 123,
  "total_spend": {},
  "total_co2e": 123,
  "total_co2e_consumption": {},
  "total_co2e_generation": {},
  "total_co2e_tnd": {},
  "count": 123,
  "quantity_by_unit": {}
}

GET

invoices

totals

Totals

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/invoices/totals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/invoices/totals"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "total_quantity": 123,
  "total_spend": {},
  "total_co2e": 123,
  "total_co2e_consumption": {},
  "total_co2e_generation": {},
  "total_co2e_tnd": {},
  "count": 123,
  "quantity_by_unit": {}
}

← Invoices API Returns 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

Example

curl -X GET "https://api.dcycle.io/v1/invoices/totals?facility_id=${FACILITY_ID}&filters=electricity&start_date=2025-01-01&end_date=2025-12-31" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}

response = requests.get(
    "https://api.dcycle.io/v1/invoices/totals",
    headers=headers,
    params={
        "facility_id": os.getenv("FACILITY_ID"),
        "filters": "electricity",
        "start_date": "2025-01-01",
        "end_date": "2025-12-31",
    },
)

totals = response.json()
print(f"CO2e: {totals['total_co2e']:.2f} tCO2e ({totals['count']} invoices)")
print(f"  Consumption: {totals.get('total_co2e_consumption', 0):.2f}")
print(f"  T&D losses:  {totals.get('total_co2e_tnd', 0):.2f}")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
};

axios.get('https://api.dcycle.io/v1/invoices/totals', {
  headers,
  params: {
    facility_id: process.env.FACILITY_ID,
    filters: 'electricity',
    start_date: '2025-01-01',
    end_date: '2025-12-31',
  },
})
.then(response => {
  const t = response.data;
  console.log(`CO2e: ${t.total_co2e.toFixed(2)} tCO2e (${t.count} invoices)`);
});

Successful Response

{
  "total_quantity": 245000.0,
  "total_spend": 48500.75,
  "total_co2e": 82.45,
  "total_co2e_consumption": 72.30,
  "total_co2e_generation": null,
  "total_co2e_tnd": 10.15,
  "count": 12,
  "quantity_by_unit": [
    {"unit_name": "kWh", "total_quantity": 245000.0, "count": 12}
  ]
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

422 Unprocessable Entity

Cause: Missing required query parameters (facility_id or type)

{
  "detail": [
    {
      "loc": ["query", "facility_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

List Invoices

Browse invoices with filters

Calculation Steps

View the CO2e conversion breakdown

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Related Endpoints

List Invoices

Calculation Steps

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Related Endpoints