> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Totals

> Get aggregated invoice totals (quantity, spend, CO2e by scope)

# Totals

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

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Query Parameters

This endpoint accepts the same filters as [List Invoices](/api-reference/invoices/list).

<ParamField query="facility_id" type="uuid" required>
  UUID of the facility to scope invoices to

  **Example:** `?facility_id=660e8400-e29b-41d4-a716-446655440000`
</ParamField>

<ParamField query="filters" type="string" required>
  Invoice type to retrieve

  **Allowed values:** `heat`, `electricity`, `water`, `recharge`, `process`

  **Example:** `?filters=electricity`
</ParamField>

<ParamField query="start_date" type="date">
  Filter invoices starting on or after this date (YYYY-MM-DD)
</ParamField>

<ParamField query="end_date" type="date">
  Filter invoices ending on or before this date (YYYY-MM-DD)
</ParamField>

<ParamField query="status[]" type="string[]">
  Filter by invoice status

  **Allowed values:** `uploaded`, `loading`, `active`, `inactive`, `review`, `error`
</ParamField>

<ParamField query="co2e_status" type="string">
  Filter by CO2e calculation status

  **Allowed values:** `calculated`, `not_calculated`
</ParamField>

<ParamField query="invoice_id" type="string">
  Partial, case-insensitive match against the invoice number

  **Example:** `?invoice_id=INV-2024`
</ParamField>

<ParamField query="cups[]" type="string[]">
  Filter by one or more CUPS codes
</ParamField>

<ParamField query="supplier_id[]" type="UUID[]">
  Filter by one or more supplier IDs
</ParamField>

<ParamField query="facility_fuel_id[]" type="UUID[]">
  Filter by one or more facility fuel IDs
</ParamField>

<ParamField query="uploaded_by[]" type="UUID[]">
  Filter by the IDs of users who uploaded the invoice
</ParamField>

<ParamField query="source[]" type="string[]">
  Filter by invoice creation source

  **Known values:** `manual`, `pdf`, `bulk_file`, `datadis`
</ParamField>

<ParamField query="created_at_start" type="date">
  Filter invoices uploaded on or after this date (YYYY-MM-DD)
</ParamField>

<ParamField query="created_at_end" type="date">
  Filter invoices uploaded on or before this date (YYYY-MM-DD)
</ParamField>

<ParamField query="stationary_fuel_id[]" type="UUID[]">
  Filter by stationary fuel IDs (natural gas, diesel, biomass). Relevant for `heat` invoices.
</ParamField>

<ParamField query="refrigerant_fuel_id[]" type="UUID[]">
  Filter by refrigerant fuel IDs. Relevant for `recharge` invoices.
</ParamField>

<ParamField query="supply_contract_id[]" type="UUID[]">
  Filter by one or more supply contract IDs
</ParamField>

<ParamField query="self_consumption[]" type="string[]">
  Filter by self-consumption flag

  **Allowed values:** `true`, `false`
</ParamField>

<ParamField query="project_id" type="uuid">
  Filter by project UUID
</ParamField>

## Response

<ResponseField name="total_quantity" type="number">
  Sum of quantities across all matching invoices
</ResponseField>

<ResponseField name="total_spend" type="number | null">
  Sum of monetary amounts (EUR)
</ResponseField>

<ResponseField name="total_co2e" type="number">
  Total CO2e (tCO2e)
</ResponseField>

<ResponseField name="total_co2e_consumption" type="number | null">
  CO2e from energy consumption (Scope 2 — market/location based)
</ResponseField>

<ResponseField name="total_co2e_generation" type="number | null">
  CO2e from on-site generation (Scope 1)
</ResponseField>

<ResponseField name="total_co2e_tnd" type="number | null">
  CO2e from transmission and distribution losses (Scope 3)
</ResponseField>

<ResponseField name="count" type="integer">
  Number of matching invoices
</ResponseField>

<ResponseField name="quantity_by_unit" type="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 |
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)`);
  });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"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`)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "facility_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Invoices" icon="list" href="/api-reference/invoices/list">
    Browse invoices with filters
  </Card>

  <Card title="Calculation Steps" icon="calculator" href="/api-reference/invoices/calculation-steps">
    View the CO2e conversion breakdown
  </Card>
</CardGroup>