Skip to main content
GET
/
v1
/
invoices
curl -X GET "https://api.dcycle.io/v1/invoices?type[]=electricity&status[]=active&page=1&size=20" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "x-api-key: YOUR_API_KEY"

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "electricity",
      "status": "active",
      "quantity": 1500.00,
      "unit_id": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",
      "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",
      "co2e": 245.5,
      "total_energy_kwh": 1500.00,
      "cups": "ES0021000000000001XX",
      "created_at": "2024-02-01T10:30:00Z",
      "updated_at": "2024-02-01T10:30:00Z",
      "confidence": {"supplier_name": 0.95, "quantity": 0.82, "start_date": 0.78}
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}

​
Overview

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

​
Query Parameters

​
type[]
string[]
Filter by invoice type. Can include multiple values.Allowed values: heat, electricity, water, rechargeExample: ?type[]=electricity&type[]=heat
​
status[]
string[]
Filter by invoice status. Can include multiple values.Allowed values: uploaded, loading, active, inactive, review, errorExample: ?status[]=active&status[]=review
​
facility_id[]
UUID[]
Filter by facility IDs. Can include multiple values.Example: ?facility_id[]=550e8400-e29b-41d4-a716-446655440000
​
start_date
date
Filter invoices starting on or after this date (YYYY-MM-DD format).Example: ?start_date=2024-01-01
​
end_date
date
Filter invoices ending on or before this date (YYYY-MM-DD format).Example: ?end_date=2024-12-31
​
co2e_status
string
Filter by whether emissions have been calculated.Allowed values: calculated, not_calculated
​
invoice_id
string
Partial, case-insensitive match against the invoice number.Example: ?invoice_id=INV-2024
​
cups[]
string[]
Filter by one or more CUPS codes.Example: ?cups[]=ES0021000000000001XX
​
supplier_id[]
UUID[]
Filter by one or more supplier IDs.
​
facility_fuel_id[]
UUID[]
Filter by one or more facility fuel IDs.
​
uploaded_by[]
UUID[]
Filter by the IDs of users who uploaded the invoice.
​
source[]
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).
​
created_at_start
date
Filter invoices uploaded on or after this date (YYYY-MM-DD format).
​
created_at_end
date
Filter invoices uploaded on or before this date (YYYY-MM-DD format).
​
stationary_fuel_id[]
UUID[]
Filter by stationary fuel IDs (natural gas, diesel, biomass, …). Relevant for heat invoices.
​
supply_contract_id[]
UUID[]
Filter by one or more supply contract IDs.
​
sort
string
Field to sort by. Prefix with - for descending order.Allowed values: start_date, end_date, created_at, quantity, invoice_idExample: ?sort=-start_date
​
page
integer
default:"1"
Page number for pagination.
​
size
integer
default:"50"
Number of items per page (max 100).

​
Response

​
items
array
List of invoice objects.
​
total
integer
Total number of invoices matching the filters.
​
page
integer
Current page number.
​
size
integer
Number of items per page.
​
pages
integer
Total number of pages.
curl -X GET "https://api.dcycle.io/v1/invoices?type[]=electricity&status[]=active&page=1&size=20" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "x-api-key: YOUR_API_KEY"

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "electricity",
      "status": "active",
      "quantity": 1500.00,
      "unit_id": "ba80e6cb-86a4-4bb1-a0c5-8104365d523c",
      "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",
      "co2e": 245.5,
      "total_energy_kwh": 1500.00,
      "cups": "ES0021000000000001XX",
      "created_at": "2024-02-01T10:30:00Z",
      "updated_at": "2024-02-01T10:30:00Z",
      "confidence": {"supplier_name": 0.95, "quantity": 0.82, "start_date": 0.78}
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}