List Invoices

Retrieve all consumption invoices (electricity, heat, water, etc.) registered for a specific facility with pagination support and flexible filtering options.

This endpoint returns invoices associated with a facility, including distributed invoices (invoices split across multiple facilities with percentage allocation).

Request

Headers

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

x-user-id

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Path Parameters

facility_id

string

required

UUID of the facility to retrieve invoices forExample: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Query Parameters

page

integer

default:"1"

Page number for paginationExample: 1

size

integer

default:"50"

Number of items per page (max: 100)Example: 50

invoice_id

string

Filter by specific invoice identifierExample: "INV-2024-001"

start_date

integer

Filter by invoice start date (Unix timestamp)Example: 1704067200 (January 1, 2024)

end_date

integer

Filter by invoice end date (Unix timestamp)Example: 1735689600 (January 1, 2025)

filters

string

Comma-separated list of invoice types to filter byValid values: heat, electricity, recharge, water, process, wastes, waste_water_treatmentExample: "electricity,heat"

filter_by

string

Advanced filtering criteria (format: field:value)Example: "status:active"

sort_by

string

Sort criteria (format: field:asc or field:desc)Example: "start_date:desc"

Response

page

integer

Current page number

size

integer

Number of items per page

total

integer

Total count of active invoices matching the filter

total2

integer

Total count of pending/loading invoices matching the filter

total_general

integer

Total count of all invoices (active + pending + error)

items

array

Array of invoice objects

Invoice Object Fields:

Basic Information:

id (string, UUID) - Unique invoice identifier
type (string) - Invoice type: "heat", "electricity", "water", "recharge", "process"
invoice_id (string, optional) - External invoice reference number
status (string) - Invoice status: "active", "loading", "error"
source (string, optional) - Invoice source: "manual", "csv", "ocr", "api"
description (string, optional) - Invoice description or notes

Quantities and Units:

quantity (float, optional) - Consumption quantity in specified unit
base_quantity (float) - Base quantity before any conversions
original_quantity (float, optional) - Original quantity if converted from currency
unit_id (string, UUID, optional) - Unit of measurement ID
unit (object, optional) - Unit details with name and type
original_unit_id (string, UUID, optional) - Original unit if converted

Dates:

start_date (datetime) - Invoice period start date
end_date (datetime) - Invoice period end date

Emissions:

co2e (float, optional) - Total CO2 equivalent emissions in kg
co2e_consumption (float, optional) - CO2e from consumption (Scope 2)
co2e_generation (float, optional) - CO2e from generation
co2e_transmission_and_distribution (float, optional) - CO2e from T&D losses
co2e_biomass (float, optional) - Biomass CO2 emissions in kg
offset (float, optional) - Emission offsets applied

Facility and Distribution:

percentage (string) - Percentage allocated to this facility
facility_percentages (array) - Distribution across facilities
- organization_id (string) - Organization UUID
- facility_id (string) - Facility UUID
- percentage (float) - Allocation percentage (0-1)
- company_name (string, optional) - Company name
- facility_name (string, optional) - Facility name
source_invoice_id (string, UUID, optional) - Parent invoice if distributed

Supplier and Fuel Information:

supplier_id (string, UUID, optional) - Supplier ID
supplier (object, optional) - Supplier details with name and country
facility_fuel_id (string, UUID, optional) - Facility fuel type ID
facility_fuel (object, optional) - Fuel details (diesel, gasoline, etc.)
cups (string, optional) - CUPS code for Spanish electricity meters

Waste-Specific Fields:

kg_sludge (float, optional) - Sludge quantity in kg (waste water treatment)
m3_water_out (float, optional) - Water output in m³ (waste water treatment)
identification_name (string, optional) - Waste identification name
total_km_to_waste_center (float, optional) - Distance to waste treatment center
low_code (string, optional) - LER/EWC waste code
rd_code (string, optional) - Spanish RD waste code

Transport-Specific Fields:

toc (string, optional) - Transport operation category for logistics

Custom Emission Factors:

custom_emission_factor_id (string, UUID, optional) - Custom factor ID
custom_emission_factor (object, optional) - Custom emission group details

File Attachments:

file_url (string, optional) - URL to attached invoice file
file_name (string, optional) - Original file name
file_id (string, UUID, optional) - File identifier

Metadata:

uploaded_by (string, optional) - User who uploaded the invoice
user (object) - User details with name and email
invofox_id (string, optional) - Invofox OCR processing ID
invoice_ocr_response (object, optional) - OCR processing response
error_messages (array of strings, optional) - Error messages if status is error

Example

curl -X GET "https://api.dcycle.io/api/v1/invoices/casted/facility/a1b2c3d4-e5f6-7890-abcd-ef1234567890?page=1&size=50&filters=electricity" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

Successful Response

{
  "page": 1,
  "size": 50,
  "total": 24,
  "total2": 3,
  "total_general": 27,
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "electricity",
      "invoice_id": "E-2024-001",
      "status": "active",
      "source": "api",
      "description": "Monthly electricity consumption",
      "quantity": 15000.0,
      "base_quantity": 15000.0,
      "original_quantity": null,
      "unit_id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
      "unit": {
        "id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
        "name": "kilowatt_hour_(kwh)",
        "type": "energy"
      },
      "original_unit_id": null,
      "start_date": "2024-11-01T00:00:00Z",
      "end_date": "2024-11-30T23:59:59Z",
      "co2e": 3450.50,
      "co2e_consumption": 3000.00,
      "co2e_generation": 150.25,
      "co2e_transmission_and_distribution": 300.25,
      "co2e_biomass": 0.0,
      "offset": 0.0,
      "percentage": "1.0",
      "facility_percentages": [
        {
          "organization_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
          "facility_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "percentage": 1.0,
          "company_name": "Acme Corp",
          "facility_name": "Madrid Office"
        }
      ],
      "source_invoice_id": null,
      "supplier_id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
      "supplier": {
        "id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
        "name": "Iberdrola",
        "country": "ES"
      },
      "facility_fuel_id": null,
      "facility_fuel": null,
      "cups": "ES0031406398765432GH0F",
      "kg_sludge": null,
      "m3_water_out": null,
      "identification_name": null,
      "total_km_to_waste_center": null,
      "low_code": null,
      "rd_code": null,
      "toc": null,
      "custom_emission_factor_id": null,
      "custom_emission_factor": null,
      "file_url": "https://s3.amazonaws.com/dcycle-files/invoices/...",
      "file_name": "electricity_nov_2024.pdf",
      "file_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
      "uploaded_by": "[email protected]",
      "user": {
        "id": "f6g7h8i9-j0k1-2345-fghi-jk6789012345",
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]"
      },
      "invofox_id": null,
      "invoice_ocr_response": null,
      "error_messages": null
    },
    {
      "id": "g7h8i9j0-k1l2-3456-ghij-kl7890123456",
      "type": "heat",
      "invoice_id": "H-2024-015",
      "status": "active",
      "source": "manual",
      "description": "Natural gas heating",
      "quantity": 5000.0,
      "base_quantity": 5000.0,
      "original_quantity": null,
      "unit_id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
      "unit": {
        "id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
        "name": "cubic_meter_(m³)",
        "type": "volume"
      },
      "original_unit_id": null,
      "start_date": "2024-11-01T00:00:00Z",
      "end_date": "2024-11-30T23:59:59Z",
      "co2e": 9820.75,
      "co2e_consumption": 9820.75,
      "co2e_generation": null,
      "co2e_transmission_and_distribution": null,
      "co2e_biomass": 0.0,
      "offset": 0.0,
      "percentage": "0.6",
      "facility_percentages": [
        {
          "organization_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
          "facility_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "percentage": 0.6,
          "company_name": "Acme Corp",
          "facility_name": "Madrid Office"
        },
        {
          "organization_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
          "facility_id": "i9j0k1l2-m3n4-5678-ijkl-mn9012345678",
          "percentage": 0.4,
          "company_name": "Acme Corp",
          "facility_name": "Barcelona Office"
        }
      ],
      "source_invoice_id": "g7h8i9j0-k1l2-3456-ghij-kl7890123456",
      "supplier_id": null,
      "supplier": null,
      "facility_fuel_id": "j0k1l2m3-n4o5-6789-klmn-no0123456789",
      "facility_fuel": {
        "id": "j0k1l2m3-n4o5-6789-klmn-no0123456789",
        "name": "Natural Gas",
        "fuel_type": "gas"
      },
      "cups": null,
      "kg_sludge": null,
      "m3_water_out": null,
      "identification_name": null,
      "total_km_to_waste_center": null,
      "low_code": null,
      "rd_code": null,
      "toc": null,
      "custom_emission_factor_id": null,
      "custom_emission_factor": null,
      "file_url": null,
      "file_name": null,
      "file_id": null,
      "uploaded_by": "[email protected]",
      "user": {
        "id": "k1l2m3n4-o5p6-7890-lmno-op1234567890",
        "first_name": "Admin",
        "last_name": "User",
        "email": "[email protected]"
      },
      "invofox_id": null,
      "invoice_ocr_response": null,
      "error_messages": null
    }
  ]
}

Common Errors

400 Bad Request - Invalid Invoice Type

Cause: Invalid value in filters parameter

{
  "detail": "INVALID_INVOICE_TYPE"
}

Solution: Use only valid filter values: heat, electricity, recharge, water, process, wastes, waste_water_treatment

403 Forbidden

Cause: Facility doesn’t belong to your organization or you don’t have access

{
  "detail": "Not authorized",
  "code": "FORBIDDEN"
}

Solution: Verify that the facility_id belongs to your organization and x-organization-id matches your API key.

404 Not Found

Cause: Facility ID doesn’t exist

{
  "detail": "Facility not found",
  "code": "NOT_FOUND"
}

Solution: Verify the facility_id is correct. Use the List Facilities endpoint to get valid facility IDs.

Use Cases

Emissions Dashboard by Facility

Display all invoices for a facility with emissions breakdown:

def get_facility_emissions_dashboard(facility_id):
    """Get emissions dashboard for a facility"""
    response = requests.get(
        f"https://api.dcycle.io/api/v1/invoices/casted/facility/{facility_id}",
        headers=headers,
        params={"page": 1, "size": 100, "sort_by": "co2e:desc"}
    )

    invoices = response.json()

    # Calculate totals by type
    emissions_by_type = {}
    for invoice in invoices['items']:
        inv_type = invoice['type']
        co2e = invoice.get('co2e', 0)

        if inv_type not in emissions_by_type:
            emissions_by_type[inv_type] = 0
        emissions_by_type[inv_type] += co2e

    return {
        'total_invoices': invoices['total'],
        'pending_invoices': invoices['total2'],
        'emissions_by_type': emissions_by_type,
        'total_emissions': sum(emissions_by_type.values())
    }

Filter by Invoice Type

Get only electricity invoices for a facility:

def get_electricity_invoices(facility_id):
    """Get only electricity invoices"""
    response = requests.get(
        f"https://api.dcycle.io/api/v1/invoices/casted/facility/{facility_id}",
        headers=headers,
        params={
            "filters": "electricity",
            "page": 1,
            "size": 100,
            "sort_by": "start_date:desc"
        }
    )

    invoices = response.json()

    print(f"Electricity invoices: {invoices['total']}")
    for invoice in invoices['items']:
        print(f"  {invoice['start_date']} - {invoice['end_date']}: "
              f"{invoice['quantity']} kWh = {invoice['co2e']:.2f} kg CO2e")

    return invoices

Filter by Date Range

Get invoices for a specific billing period:

from datetime import datetime

def get_invoices_for_period(facility_id, year, month):
    """Get invoices for a specific month"""
    # Calculate start and end timestamps
    start = datetime(year, month, 1)
    if month == 12:
        end = datetime(year + 1, 1, 1)
    else:
        end = datetime(year, month + 1, 1)

    start_ts = int(start.timestamp())
    end_ts = int(end.timestamp())

    response = requests.get(
        f"https://api.dcycle.io/api/v1/invoices/casted/facility/{facility_id}",
        headers=headers,
        params={
            "start_date": start_ts,
            "end_date": end_ts,
            "page": 1,
            "size": 100
        }
    )

    invoices = response.json()

    print(f"Invoices for {year}-{month:02d}: {len(invoices['items'])}")
    total_emissions = sum(inv.get('co2e', 0) for inv in invoices['items'])
    print(f"Total emissions: {total_emissions:.2f} kg CO2e")

    return invoices

# Example: Get invoices for November 2024
november_invoices = get_invoices_for_period("facility-id", 2024, 11)

Multiple Invoice Types

Get both electricity and heat invoices:

def get_energy_invoices(facility_id):
    """Get electricity and heat invoices"""
    response = requests.get(
        f"https://api.dcycle.io/api/v1/invoices/casted/facility/{facility_id}",
        headers=headers,
        params={
            "filters": "electricity,heat",
            "page": 1,
            "size": 100
        }
    )

    invoices = response.json()

    # Separate by type
    electricity = [i for i in invoices['items'] if i['type'] == 'electricity']
    heat = [i for i in invoices['items'] if i['type'] == 'heat']

    print(f"Electricity invoices: {len(electricity)}")
    print(f"Heat invoices: {len(heat)}")

    return {
        'electricity': electricity,
        'heat': heat
    }

Pagination

Retrieve all invoices using pagination:

def get_all_facility_invoices(facility_id):
    """Fetch all invoices for a facility with pagination"""
    all_invoices = []
    page = 1

    while True:
        response = requests.get(
            f"https://api.dcycle.io/api/v1/invoices/casted/facility/{facility_id}",
            headers=headers,
            params={"page": page, "size": 100}
        )

        data = response.json()
        all_invoices.extend(data['items'])

        # Check if we've retrieved all items
        if len(all_invoices) >= data['total_general']:
            break

        page += 1

    return all_invoices

# Get all invoices
all_invoices = get_all_facility_invoices("facility-id")
print(f"Total invoices retrieved: {len(all_invoices)}")

Special Notes

Invoice Types

Dcycle supports multiple invoice types for comprehensive emissions tracking:

electricity: Electric power consumption (Scope 2)
heat: Heating fuels (natural gas, diesel, etc.) (Scope 1)
water: Water consumption (Scope 3)
recharge: Electric vehicle charging (Scope 1 or 2)
process: Industrial process emissions (Scope 1)
wastes: Waste generation and treatment (Scope 3)
waste_water_treatment: Wastewater treatment (Scope 3)

Invoice Status

Invoices can have three statuses:

active: Invoice processed successfully with calculated emissions
loading: Invoice uploaded but processing is pending
error: Invoice processing failed (check error_messages field)

Distributed Invoices

When an invoice is distributed across multiple facilities:

percentage shows the allocation to the current facility (0-1 range)
facility_percentages array shows complete distribution
source_invoice_id references the parent invoice
CO2e is automatically calculated proportionally

This is useful for:

Shared utility bills across multiple locations
Corporate headquarters distributing costs to subsidiaries
Multi-tenant buildings

CO2e Breakdown

For electricity invoices, emissions are broken down into:

co2e_consumption: Direct consumption emissions (Scope 2)
co2e_generation: Upstream generation emissions
co2e_transmission_and_distribution: T&D line losses (Scope 3)
co2e: Total emissions (sum of all components)

CUPS Codes

For Spanish electricity invoices, the cups field contains the Código Universal del Punto de Suministro (Universal Supply Point Code), which uniquely identifies the electricity meter.

Response Counts Explanation

The response includes three different totals:

total: Count of active/processed invoices matching your filter
total2: Count of pending/loading invoices matching your filter
total_general: Total count of all invoices (active + pending + error) returned by pagination

Use total and total2 to display processing status in your UI. Use total_general for pagination calculations.

Create Invoice

Add new consumption invoices

List Facilities

Get facility IDs for invoice queries

Bulk Upload Invoices

Upload multiple invoices via CSV

Authentication

Learn about API authentication

Introduction

Logistics

Facilities

Vehicles

Invoices

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

List Invoices

List Invoices

Request

Headers

Path Parameters

Query Parameters

Response

Invoice Object Fields:

Example

Successful Response

Common Errors

400 Bad Request - Invalid Invoice Type

403 Forbidden

404 Not Found

Use Cases

Emissions Dashboard by Facility

Filter by Invoice Type

Filter by Date Range

Multiple Invoice Types

Special Notes

Invoice Types

Invoice Status

Distributed Invoices

CO2e Breakdown

CUPS Codes

Response Counts Explanation

Create Invoice

List Facilities

Bulk Upload Invoices

Authentication

Introduction

Logistics

Facilities

Vehicles

Invoices

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

​List Invoices

​Request

​Headers

​Path Parameters

​Query Parameters

​Response

​Invoice Object Fields:

​Example

​Successful Response

​Common Errors

​400 Bad Request - Invalid Invoice Type

​403 Forbidden

​404 Not Found

​Use Cases

​Emissions Dashboard by Facility

​Filter by Invoice Type

​Filter by Date Range

​Multiple Invoice Types

​Pagination

​Special Notes

​Invoice Types

​Invoice Status

​Distributed Invoices

​CO2e Breakdown

​CUPS Codes

​Response Counts Explanation

​Related Endpoints

Create Invoice

List Facilities

Bulk Upload Invoices

Authentication

List Invoices

Request

Headers

Path Parameters

Query Parameters

Response

Invoice Object Fields:

Example

Successful Response

Common Errors

400 Bad Request - Invalid Invoice Type

403 Forbidden

404 Not Found

Use Cases

Emissions Dashboard by Facility

Filter by Invoice Type

Filter by Date Range

Multiple Invoice Types

Pagination

Special Notes

Invoice Types

Invoice Status

Distributed Invoices

CO2e Breakdown

CUPS Codes

Response Counts Explanation

Related Endpoints