List Invoices

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/invoices"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/invoices \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": [
    {
      "id": "<string>",
      "type": "<string>",
      "status": "<string>",
      "quantity": {},
      "unit": {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>"
      },
      "start_date": {},
      "end_date": {},
      "invoice_id": {},
      "facility_id": {},
      "supplier": {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>",
        "country": {}
      },
      "co2e": {},
      "total_energy_kwh": {},
      "co2e_consumption": {},
      "co2e_generation": {},
      "co2e_transmission_and_distribution": {},
      "co2e_location_based": {},
      "self_consumption": true,
      "cups": {},
      "source": {},
      "file_url": {},
      "total_spend": {},
      "currency_unit_id": {},
      "uploaded_by": {},
      "user": {
        "id": "<string>",
        "first_name": {},
        "last_name": {},
        "email": "<string>",
        "prefix": {},
        "phone_number": {},
        "onboarding_done": true,
        "profile_img_url": {}
      },
      "facility_fuel": {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>",
        "country": {}
      },
      "stationary_fuel": {
        "id": "<string>",
        "name": "<string>"
      },
      "refrigerant_fuel": {
        "id": "<string>",
        "name": "<string>"
      },
      "linked_projects": [
        {}
      ],
      "confidence": {},
      "created_at": {},
      "updated_at": {}
    }
  ],
  "total": 123,
  "total2": 123,
  "total_general": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

GET

invoices

List Invoices

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/invoices"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/invoices \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": [
    {
      "id": "<string>",
      "type": "<string>",
      "status": "<string>",
      "quantity": {},
      "unit": {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>"
      },
      "start_date": {},
      "end_date": {},
      "invoice_id": {},
      "facility_id": {},
      "supplier": {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>",
        "country": {}
      },
      "co2e": {},
      "total_energy_kwh": {},
      "co2e_consumption": {},
      "co2e_generation": {},
      "co2e_transmission_and_distribution": {},
      "co2e_location_based": {},
      "self_consumption": true,
      "cups": {},
      "source": {},
      "file_url": {},
      "total_spend": {},
      "currency_unit_id": {},
      "uploaded_by": {},
      "user": {
        "id": "<string>",
        "first_name": {},
        "last_name": {},
        "email": "<string>",
        "prefix": {},
        "phone_number": {},
        "onboarding_done": true,
        "profile_img_url": {}
      },
      "facility_fuel": {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>",
        "country": {}
      },
      "stationary_fuel": {
        "id": "<string>",
        "name": "<string>"
      },
      "refrigerant_fuel": {
        "id": "<string>",
        "name": "<string>"
      },
      "linked_projects": [
        {}
      ],
      "confidence": {},
      "created_at": {},
      "updated_at": {}
    }
  ],
  "total": 123,
  "total2": 123,
  "total_general": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

uuid

required

UUID of the facility to retrieve invoices forExample: ?facility_id=660e8400-e29b-41d4-a716-446655440000

string

required

Invoice type to retrieveAllowed values: heat, electricity, water, recharge, processExample: ?filters=electricity

string[]

Filter by invoice status. Can include multiple values.Allowed values: uploaded, loading, active, inactive, review, errorExample: ?status[]=active&status[]=review

date

Filter invoices starting on or after this date (YYYY-MM-DD format).Example: ?start_date=2024-01-01

date

Filter invoices ending on or before this date (YYYY-MM-DD format).Example: ?end_date=2024-12-31

string

Filter by whether emissions have been calculated.Allowed values: calculated, not_calculated

string

Partial, case-insensitive match against the invoice number.Example: ?invoice_id=INV-2024

string[]

Filter by one or more CUPS codes.Example: ?cups[]=ES0021000000000001XX

UUID[]

Filter by one or more supplier IDs.

UUID[]

Filter by one or more facility fuel IDs.

UUID[]

Filter by the IDs of users who uploaded the invoice.

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

date

Filter invoices uploaded on or after this date (YYYY-MM-DD format).

date

Filter invoices uploaded on or before this date (YYYY-MM-DD format).

UUID[]

Filter by stationary fuel IDs (natural gas, diesel, biomass, …). Relevant for heat invoices.

UUID[]

Filter by refrigerant fuel IDs. Relevant for recharge invoices.

UUID[]

Filter by one or more supply contract IDs.

string[]

Filter by self-consumption flagAllowed values: true, false

uuid

Filter by project UUID

string

Field to sort by. Prefix with - for descending order.Allowed values: start_date, end_date, created_at, quantity, invoice_idExample: ?sort=-start_date

integer

default:"1"

Page number for pagination.

integer

default:"50"

Number of items per page (max 100).

Response

array

List of invoice objects.

Show Invoice object properties

string

UUID of the invoice

string

Invoice type: heat, electricity, water, or recharge

string

Current status: uploaded, loading, active, inactive, review, or error

float | null

Consumption amount in the unit specified by unit

object | null

Unit of measurement

Show Unit object

string

UUID

string

Display name (e.g. "kWh", "m³")

string

Unit category

datetime

Billing period start date

datetime

Billing period end date

string | null

Invoice number from the utility provider

string | null

UUID of the associated facility

object | null

Energy supplier

Show Supplier object

string

UUID

string

Supplier name

string

Supplier type

string | null

Country code

float | null

Calculated CO2 equivalent emissions (kg CO2e)

float | null

Total energy in kWh. Only for electricity and heat invoices. null if calculation has not completed.

float | null

Emissions from energy consumption (kg CO2e). Only for electricity and heat invoices.

float | null

Emissions from energy generation (kg CO2e). Only for electricity and heat invoices.

float | null

Emissions from transmission and distribution losses (kg CO2e). Only for electricity and heat invoices.

float | null

Location-based emissions (kg CO2e). Only for electricity invoices.

boolean

Whether this is a self-consumption invoice. Only for electricity invoices.

string | null

CUPS code (Spanish electricity supply point identifier)

string | null

How the invoice was created: manual, pdf, bulk_file, or datadis

string | null

URL to the uploaded file, if any

float | null

Total monetary cost of the invoice

string | null

UUID of the currency unit for total_spend

string | null

UUID of the user who uploaded the invoice

object | null

User who uploaded the invoice

Show User object

string

User UUID

string | null

First name

string | null

Last name

string

Email address

string | null

Phone prefix

string | null

Phone number

boolean

Whether onboarding is complete

string | null

Profile image URL

object | null

Facility fuel type. Present for heat invoices.

Show Facility fuel object

string

UUID

string

Fuel name

string

Fuel type

string | null

Country code

object | null

Stationary fuel. Present for heat invoices with stationary combustion.

Show Stationary fuel object

string

UUID

string

Fuel name

object | null

Refrigerant fuel. Present for recharge invoices.

Show Refrigerant fuel object

string

UUID

string

Refrigerant name

array

Projects linked to this invoice

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}

datetime

When the invoice was created

datetime | null

When the invoice was last updated

integer

Count of invoices with active or uploaded status matching filters

integer

Count of invoices with loading or pending status matching filters

integer

Total number of all invoices matching the filters (all statuses)

integer

Current page number

integer

Number of items per page

string

16-character hex hash of the applied filters. Pass this to the bulk delete by filters endpoint to ensure consistency.

Example

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}"

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")

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`);

Successful Response

{
  "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

{"detail": "Invalid or missing API key"}

Get Invoice

Get a single invoice by ID

Create Invoice

Update Invoice

Modify invoice details

Filter Options

Get available filter values for dropdowns

Invoices API Totals

​List Invoices

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​Related Endpoints

Get Invoice

Create Invoice

Update Invoice

Filter Options

List Invoices

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

Related Endpoints