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

# List Invoices

> Retrieve all invoices with filtering and pagination

# List Invoices

Retrieve a paginated list of invoices for your organization. Use query parameters to filter by type, status, facility, and date range.

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

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

  **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="status[]" type="string[]">
  Filter by invoice status. Can include multiple values.

  **Allowed values:** `uploaded`, `loading`, `active`, `inactive`, `review`, `error`

  **Example:** `?status[]=active&status[]=review`
</ParamField>

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

  **Example:** `?start_date=2024-01-01`
</ParamField>

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

  **Example:** `?end_date=2024-12-31`
</ParamField>

<ParamField query="co2e_status" type="string">
  Filter by whether emissions have been calculated.

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

  **Example:** `?cups[]=ES0021000000000001XX`
</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`. Sending
  `manual` also matches invoices where `source` is `NULL` (legacy rows
  written before explicit source tracking).
</ParamField>

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

<ParamField query="created_at_end" type="date">
  Filter invoices uploaded on or before this date (YYYY-MM-DD format).
</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>

<ParamField query="sort" type="string">
  Field to sort by. Prefix with `-` for descending order.

  **Allowed values:** `start_date`, `end_date`, `created_at`, `quantity`, `invoice_id`

  **Example:** `?sort=-start_date`
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="size" type="integer" default="50">
  Number of items per page (max 100).
</ParamField>

## Response

<ResponseField name="items" type="array">
  List of invoice objects.

  <Expandable title="Invoice object properties">
    <ResponseField name="id" type="string">
      UUID of the invoice
    </ResponseField>

    <ResponseField name="type" type="string">
      Invoice type: `heat`, `electricity`, `water`, or `recharge`
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `uploaded`, `loading`, `active`, `inactive`, `review`, or `error`
    </ResponseField>

    <ResponseField name="quantity" type="float | null">
      Consumption amount in the unit specified by `unit`
    </ResponseField>

    <ResponseField name="unit" type="object | null">
      Unit of measurement

      <Expandable title="Unit object">
        <ResponseField name="id" type="string">UUID</ResponseField>
        <ResponseField name="name" type="string">Display name (e.g. `"kWh"`, `"m³"`)</ResponseField>
        <ResponseField name="type" type="string">Unit category</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="start_date" type="datetime">
      Billing period start date
    </ResponseField>

    <ResponseField name="end_date" type="datetime">
      Billing period end date
    </ResponseField>

    <ResponseField name="invoice_id" type="string | null">
      Invoice number from the utility provider
    </ResponseField>

    <ResponseField name="facility_id" type="string | null">
      UUID of the associated facility
    </ResponseField>

    <ResponseField name="supplier" type="object | null">
      Energy supplier

      <Expandable title="Supplier object">
        <ResponseField name="id" type="string">UUID</ResponseField>
        <ResponseField name="name" type="string">Supplier name</ResponseField>
        <ResponseField name="type" type="string">Supplier type</ResponseField>
        <ResponseField name="country" type="string | null">Country code</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="co2e" type="float | null">
      Calculated CO2 equivalent emissions (kg CO2e)
    </ResponseField>

    <ResponseField name="total_energy_kwh" type="float | null">
      Total energy in kWh. Only for `electricity` and `heat` invoices. `null` if calculation has not completed.
    </ResponseField>

    <ResponseField name="co2e_consumption" type="float | null">
      Emissions from energy consumption (kg CO2e). Only for `electricity` and `heat` invoices.
    </ResponseField>

    <ResponseField name="co2e_generation" type="float | null">
      Emissions from energy generation (kg CO2e). Only for `electricity` and `heat` invoices.
    </ResponseField>

    <ResponseField name="co2e_transmission_and_distribution" type="float | null">
      Emissions from transmission and distribution losses (kg CO2e). Only for `electricity` and `heat` invoices.
    </ResponseField>

    <ResponseField name="co2e_location_based" type="float | null">
      Location-based emissions (kg CO2e). Only for `electricity` invoices.
    </ResponseField>

    <ResponseField name="self_consumption" type="boolean">
      Whether this is a self-consumption invoice. Only for `electricity` invoices.
    </ResponseField>

    <ResponseField name="cups" type="string | null">
      CUPS code (Spanish electricity supply point identifier)
    </ResponseField>

    <ResponseField name="source" type="string | null">
      How the invoice was created: `manual`, `pdf`, `bulk_file`, or `datadis`
    </ResponseField>

    <ResponseField name="file_url" type="string | null">
      URL to the uploaded file, if any
    </ResponseField>

    <ResponseField name="total_spend" type="float | null">
      Total monetary cost of the invoice
    </ResponseField>

    <ResponseField name="currency_unit_id" type="string | null">
      UUID of the currency unit for `total_spend`
    </ResponseField>

    <ResponseField name="uploaded_by" type="string | null">
      UUID of the user who uploaded the invoice
    </ResponseField>

    <ResponseField name="user" type="object | null">
      User who uploaded the invoice

      <Expandable title="User object">
        <ResponseField name="id" type="string">User UUID</ResponseField>
        <ResponseField name="first_name" type="string | null">First name</ResponseField>
        <ResponseField name="last_name" type="string | null">Last name</ResponseField>
        <ResponseField name="email" type="string">Email address</ResponseField>
        <ResponseField name="prefix" type="string | null">Phone prefix</ResponseField>
        <ResponseField name="phone_number" type="string | null">Phone number</ResponseField>
        <ResponseField name="onboarding_done" type="boolean">Whether onboarding is complete</ResponseField>
        <ResponseField name="profile_img_url" type="string | null">Profile image URL</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="facility_fuel" type="object | null">
      Facility fuel type. Present for `heat` invoices.

      <Expandable title="Facility fuel object">
        <ResponseField name="id" type="string">UUID</ResponseField>
        <ResponseField name="name" type="string">Fuel name</ResponseField>
        <ResponseField name="type" type="string">Fuel type</ResponseField>
        <ResponseField name="country" type="string | null">Country code</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stationary_fuel" type="object | null">
      Stationary fuel. Present for `heat` invoices with stationary combustion.

      <Expandable title="Stationary fuel object">
        <ResponseField name="id" type="string">UUID</ResponseField>
        <ResponseField name="name" type="string">Fuel name</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="refrigerant_fuel" type="object | null">
      Refrigerant fuel. Present for `recharge` invoices.

      <Expandable title="Refrigerant fuel object">
        <ResponseField name="id" type="string">UUID</ResponseField>
        <ResponseField name="name" type="string">Refrigerant name</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="linked_projects" type="array">
      Projects linked to this invoice
    </ResponseField>

    <ResponseField name="confidence" type="object | null">
      Per-field OCR confidence scores. Only present for invoices uploaded via PDF.

      **Example:** `{"supplier_name": 0.95, "quantity": 0.82, "start_date": 0.78}`
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      When the invoice was created
    </ResponseField>

    <ResponseField name="updated_at" type="datetime | null">
      When the invoice was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Count of invoices with `active` or `uploaded` status matching filters
</ResponseField>

<ResponseField name="total2" type="integer">
  Count of invoices with `loading` or `pending` status matching filters
</ResponseField>

<ResponseField name="total_general" type="integer">
  Total number of all invoices matching the filters (all statuses)
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="size" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="filter_hash" type="string">
  16-character hex hash of the applied filters. Pass this to the [bulk delete by filters](/api-reference/invoices/bulk-delete-by-filters) endpoint to ensure consistency.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/invoices?facility_id=660e8400-e29b-41d4-a716-446655440000&filters=electricity&status[]=active&page=1&size=20" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "x-api-key: ${DCYCLE_API_KEY}"
  ```

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

  response = requests.get(
      "https://api.dcycle.io/v1/invoices",
      headers={
          "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
          "x-api-key": os.getenv("DCYCLE_API_KEY"),
      },
      params={
          "facility_id": "660e8400-e29b-41d4-a716-446655440000",
          "filters": "electricity",
          "status[]": ["active"],
          "page": 1,
          "size": 20,
      },
  )

  invoices = response.json()
  print(f"Found {invoices['total']} invoices")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const response = await axios.get(
    'https://api.dcycle.io/v1/invoices',
    {
      headers: {
        'x-organization-id': process.env.DCYCLE_ORG_ID,
        'x-api-key': process.env.DCYCLE_API_KEY,
      },
      params: {
        facility_id: '660e8400-e29b-41d4-a716-446655440000',
        filters: 'electricity',
        'status[]': ['active'],
        page: 1,
        size: 20,
      },
    }
  );

  console.log(`Found ${response.data.total} invoices`);
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "electricity",
      "status": "active",
      "quantity": 1500.0,
      "unit": {
        "id": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",
        "name": "kWh",
        "type": "energy"
      },
      "start_date": "2024-01-01T00:00:00",
      "end_date": "2024-01-31T23:59:59",
      "invoice_id": "INV-2024-001",
      "facility_id": "660e8400-e29b-41d4-a716-446655440000",
      "supplier": {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "name": "Iberdrola",
        "type": "electricity",
        "country": "ES"
      },
      "co2e": 245.5,
      "total_energy_kwh": 1500.0,
      "co2e_consumption": 210.3,
      "co2e_generation": 15.2,
      "co2e_transmission_and_distribution": 20.0,
      "co2e_location_based": 300.1,
      "self_consumption": false,
      "cups": "ES0021000000000001XX",
      "source": "pdf",
      "file_url": "https://storage.dcycle.io/invoices/550e8400.pdf",
      "total_spend": 285.50,
      "currency_unit_id": "eur-uuid",
      "uploaded_by": "user-uuid",
      "user": {
        "id": "user-uuid",
        "first_name": "Ana",
        "last_name": "García",
        "email": "ana@company.com",
        "prefix": null,
        "phone_number": null,
        "onboarding_done": true,
        "profile_img_url": null
      },
      "facility_fuel": null,
      "stationary_fuel": null,
      "refrigerant_fuel": null,
      "linked_projects": [],
      "confidence": { "supplier_name": 0.95, "quantity": 0.82, "start_date": 0.78 },
      "created_at": "2024-02-01T10:30:00Z",
      "updated_at": "2024-02-01T10:30:00Z"
    }
  ],
  "total": 1,
  "total2": 0,
  "total_general": 1,
  "page": 1,
  "size": 20,
  "filter_hash": "a1b2c3d4e5f67890"
}
```

## Common Errors

### 401 Unauthorized

**Cause:** Invalid or missing API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid or missing API key"}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Invoice" icon="file-invoice" href="/api-reference/invoices/get">
    Get a single invoice by ID
  </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="Filter Options" icon="filter" href="/api-reference/invoices/filter-options">
    Get available filter values for dropdowns
  </Card>
</CardGroup>