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

# Invoices API

> Retrieve detailed invoice data for energy and utility consumption including emissions calculations

# Invoices API

The Invoices API allows you to retrieve, update, and delete invoice records for tracking energy consumption emissions. Invoices cover multiple energy sources including electricity, natural gas, fuel deliveries, water, electric vehicle recharging, and industrial processes.

<Note>
  **GHG Protocol — Multiple Scopes**

  Invoices cover emissions across multiple GHG Protocol scopes:

  * **Scope 1**: Direct emissions from fuel combustion — `heat`, `recharge`, and `process` invoices
  * **Scope 2**: Indirect emissions from purchased energy — `electricity` invoices

  This API helps you manage the data needed for accurate Scope 1 and 2 reporting.
</Note>

## Key Features

* **Discriminated Response**: Response shape varies by invoice type (`heat`, `electricity`, `water`, `recharge`, `process`)
* **Facility Allocation**: View how invoices are allocated across facilities with percentage breakdowns
* **CO2e Tracking**: View calculated emissions including biomass breakdown for each invoice
* **Custom Emission Factors**: Support for supplier-specific and custom emission factors
* **Multiple Energy Types**: Support for electricity, heat, water, recharging, and process invoices

## Authentication

All endpoints require authentication using an API key included in the `x-api-key` header.

## Headers

All requests must include:

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

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

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

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

## Available Endpoints

<CardGroup cols={2}>
  <Card title="List Invoices" icon="list" href="/api-reference/invoices/list">
    Retrieve all invoices with filtering and pagination
  </Card>

  <Card title="Get Invoice" icon="receipt" href="/api-reference/invoices/get">
    Get a specific invoice by ID with full detail
  </Card>

  <Card title="Create Invoice" icon="plus" href="/api-reference/invoices/create">
    Register a new consumption invoice
  </Card>

  <Card title="Update Invoice" icon="pencil" href="/api-reference/invoices/update">
    Modify invoice details
  </Card>

  <Card title="Delete Invoice" icon="trash" href="/api-reference/invoices/delete">
    Remove an invoice from your organization
  </Card>
</CardGroup>

## Data Model

### Invoice Object

The invoice object contains detailed information about an energy or utility invoice. The response is a discriminated union — the `type` field determines which additional fields are present:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "electricity",
  "quantity": 1500.00,
  "base_quantity": 3000.00,
  "percentage": 0.5,
  "status": "active",
  "co2e": 245.5,
  "co2e_biomass": 0,
  "start_date": "2024-01-01T00:00:00",
  "end_date": "2024-01-31T23:59:59",
  "unit_id": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",
  "original_quantity": null,
  "original_unit_id": null,
  "facility_id": "660e8400-e29b-41d4-a716-446655440000",
  "uploaded_by": "990e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "INV-2024-001",
  "cups": "ES0021000000000001XX",
  "file_url": "https://storage.dcycle.io/invoices/invoice-2024-001.pdf",
  "source_invoice_id": null,
  "enabled": true,
  "created_at": "2024-02-01T10:30:00Z",
  "updated_at": "2024-02-01T10:30:00Z",
  "toc_id": null,
  "invofox_id": null,
  "facility_percentages": [
    {
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "facility_id": "660e8400-e29b-41d4-a716-446655440000",
      "percentage": 0.5,
      "company_name": "Acme Corp",
      "facility_name": "Madrid Office"
    }
  ],
  "supplier_id": "770e8400-e29b-41d4-a716-446655440000",
  "custom_emission_factor_id": null,
  "custom_emission_factor": null
}
```

### Invoice Attributes

| Field                  | Type     | Description                                                         |
| ---------------------- | -------- | ------------------------------------------------------------------- |
| `id`                   | UUID     | Unique identifier for the invoice                                   |
| `type`                 | string   | Invoice type: `heat`, `electricity`, `water`, `recharge`, `process` |
| `quantity`             | float    | Consumption amount after facility allocation                        |
| `base_quantity`        | float    | Original consumption amount before facility allocation              |
| `percentage`           | float    | Facility allocation percentage (0-1)                                |
| `status`               | string   | Invoice status (see Status Types)                                   |
| `co2e`                 | float    | Calculated CO2 equivalent emissions (kg)                            |
| `co2e_biomass`         | float    | CO2e from biomass sources (kg)                                      |
| `start_date`           | datetime | Billing period start date                                           |
| `end_date`             | datetime | Billing period end date                                             |
| `unit_id`              | UUID     | Unit of measurement                                                 |
| `original_quantity`    | float    | Original quantity before conversions                                |
| `original_unit_id`     | UUID     | Original unit before conversions                                    |
| `facility_id`          | UUID     | Associated facility                                                 |
| `uploaded_by`          | UUID     | User who uploaded the invoice                                       |
| `invoice_id`           | string   | External invoice identifier from utility provider                   |
| `cups`                 | string   | CUPS code (for Spanish electricity)                                 |
| `file_url`             | string   | URL to download linked file                                         |
| `source_invoice_id`    | UUID     | Source invoice (if derived from another invoice)                    |
| `enabled`              | boolean  | Whether invoice is enabled                                          |
| `created_at`           | datetime | When the invoice was created                                        |
| `updated_at`           | datetime | When the invoice was last updated                                   |
| `toc_id`               | UUID     | TOC identifier                                                      |
| `invofox_id`           | string   | Invofox integration ID                                              |
| `facility_percentages` | array    | Facility percentage allocations (see below)                         |

### Type-Specific Fields

| Field                       | Types                             | Description                             |
| --------------------------- | --------------------------------- | --------------------------------------- |
| `facility_fuel_id`          | `heat`, `recharge`                | Fuel type UUID                          |
| `custom_emission_factor_id` | `heat`, `electricity`, `recharge` | Custom emission factor UUID             |
| `custom_emission_factor`    | `heat`, `electricity`, `recharge` | Custom emission factor details (object) |
| `supplier_id`               | `heat`, `electricity`, `recharge` | Energy supplier UUID                    |

### Facility Percentage Object

| Field             | Type   | Description                 |
| ----------------- | ------ | --------------------------- |
| `organization_id` | UUID   | Organization UUID           |
| `facility_id`     | UUID   | Facility UUID               |
| `percentage`      | float  | Allocation percentage (0-1) |
| `company_name`    | string | Company name                |
| `facility_name`   | string | Facility name               |

## Invoice Types

| Type          | Description                            | GHG Scope               |
| ------------- | -------------------------------------- | ----------------------- |
| `heat`        | Natural gas and fuel delivery invoices | Scope 1                 |
| `electricity` | Electricity consumption invoices       | Scope 2                 |
| `water`       | Water consumption invoices             | Scope 3 (if applicable) |
| `recharge`    | Electric vehicle recharging            | Scope 2                 |
| `process`     | Industrial process emissions           | Scope 1                 |

## Status Types

| Status     | Description                                   |
| ---------- | --------------------------------------------- |
| `uploaded` | Invoice uploaded, awaiting processing         |
| `loading`  | Invoice being processed                       |
| `active`   | Invoice active and included in calculations   |
| `inactive` | Invoice inactive (excluded from calculations) |
| `review`   | Invoice under review                          |
| `error`    | Error occurred during processing              |

## CO2e Calculation

Emissions are calculated based on invoice type and associated emission factors:

### Electricity (Scope 2)

```
CO2e = kWh consumed x Grid emission factor (kg CO2e/kWh)
```

### Heat/Combustion (Scope 1)

```
CO2e = Fuel quantity x Fuel emission factor (kg CO2e/unit)
```

### Process (Scope 1)

```
CO2e = Process quantity x Process emission factor (kg CO2e/unit)
```

## Error Handling

### Common HTTP Status Codes

| Status | Meaning                        | Solution                                    |
| ------ | ------------------------------ | ------------------------------------------- |
| 200    | Success                        | -                                           |
| 204    | No Content (delete successful) | -                                           |
| 400    | Bad Request                    | Check request parameters and format         |
| 401    | Unauthorized                   | Verify API key                              |
| 403    | Forbidden                      | Invoice doesn't belong to your organization |
| 404    | Not Found                      | Check resource ID                           |
| 422    | Validation Error               | Review error details in response            |
| 500    | Server Error                   | Contact support if persists                 |

### Error Response Format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Error description",
  "code": "ERROR_CODE"
}
```

## Use Cases

### Track Electricity Consumption

Monitor electricity invoices for Scope 2 reporting:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

# Get all electricity invoices
response = requests.get(
    "https://api.dcycle.io/v1/invoices",
    headers=headers,
    params={"type[]": ["electricity"], "status[]": ["active"]}
)

invoices = response.json()["items"]
total_co2e = sum(inv.get("co2e", 0) for inv in invoices)
print(f"Scope 2 emissions: {total_co2e} kg CO2e")
```

### Calculate Scope 1 from Fuel Invoices

Sum up direct emissions from fuel consumption:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Get all heat/combustion invoices
response = requests.get(
    "https://api.dcycle.io/v1/invoices",
    headers=headers,
    params={"type[]": ["heat", "process"], "status[]": ["active"]}
)

invoices = response.json()["items"]
total_co2e = sum(inv.get("co2e", 0) for inv in invoices)
print(f"Scope 1 emissions: {total_co2e} kg CO2e")
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Scope 1 & 2 Guide" icon="bolt" href="/guides/emissions/ghg-protocol-step-2-scope-1">
    Complete tutorial for tracking Scope 1 and 2 emissions
  </Card>

  <Card title="Facilities API" icon="building" href="/api-reference/legacy/facilities/list">
    Manage facility data
  </Card>

  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Custom Emission Factors" icon="chart-line" href="/api-reference/legacy/custom-emission-factors/overview">
    Create custom emission factors
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/invoices">
    Query invoice data from AI assistants via MCP
  </Card>
</CardGroup>