> ## 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.

# Invoice Tools

> MCP tools for querying energy invoices and consumption data (Scope 1 & 2)

# 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.

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

## `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:**

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

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

## Related

<CardGroup cols={2}>
  <Card title="API: List Invoices" icon="code" href="/api-reference/invoices/list">
    REST API equivalent with additional filters
  </Card>

  <Card title="Facilities" icon="building" href="/mcp/facilities">
    Find facility IDs to query invoices
  </Card>

  <Card title="Emissions" icon="smog" href="/mcp/emissions">
    Aggregated Scope 1 & 2 emissions
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/assets">
    Manage invoices from the command line
  </Card>
</CardGroup>