Skip to main content

​
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.
GHG Protocol — Multiple ScopesInvoices 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.

​
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 either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests must include:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef

​
Available Endpoints

List Invoices

Retrieve all invoices with filtering and pagination

Get Invoice

Get a specific invoice by ID with full detail

Update Invoice

Modify invoice details

Delete Invoice

Remove an invoice from your organization

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

FieldTypeDescription
idUUIDUnique identifier for the invoice
typestringInvoice type: heat, electricity, water, recharge, process
quantityfloatConsumption amount after facility allocation
base_quantityfloatOriginal consumption amount before facility allocation
percentagefloatFacility allocation percentage (0-1)
statusstringInvoice status (see Status Types)
co2efloatCalculated CO2 equivalent emissions (kg)
co2e_biomassfloatCO2e from biomass sources (kg)
start_datedatetimeBilling period start date
end_datedatetimeBilling period end date
unit_idUUIDUnit of measurement
original_quantityfloatOriginal quantity before conversions
original_unit_idUUIDOriginal unit before conversions
facility_idUUIDAssociated facility
uploaded_byUUIDUser who uploaded the invoice
invoice_idstringExternal invoice identifier from utility provider
cupsstringCUPS code (for Spanish electricity)
file_urlstringURL to download linked file
source_invoice_idUUIDSource invoice (if derived from another invoice)
enabledbooleanWhether invoice is enabled
created_atdatetimeWhen the invoice was created
updated_atdatetimeWhen the invoice was last updated
toc_idUUIDTOC identifier
invofox_idstringInvofox integration ID
facility_percentagesarrayFacility percentage allocations (see below)

​
Type-Specific Fields

FieldTypesDescription
facility_fuel_idheat, rechargeFuel type UUID
custom_emission_factor_idheat, electricity, rechargeCustom emission factor UUID
custom_emission_factorheat, electricity, rechargeCustom emission factor details (object)
supplier_idheat, electricity, rechargeEnergy supplier UUID

​
Facility Percentage Object

FieldTypeDescription
organization_idUUIDOrganization UUID
facility_idUUIDFacility UUID
percentagefloatAllocation percentage (0-1)
company_namestringCompany name
facility_namestringFacility name

​
Invoice Types

TypeDescriptionGHG Scope
heatNatural gas and fuel delivery invoicesScope 1
electricityElectricity consumption invoicesScope 2
waterWater consumption invoicesScope 3 (if applicable)
rechargeElectric vehicle rechargingScope 2
processIndustrial process emissionsScope 1

​
Status Types

StatusDescription
uploadedInvoice uploaded, awaiting processing
loadingInvoice being processed
activeInvoice active and included in calculations
inactiveInvoice inactive (excluded from calculations)
reviewInvoice under review
errorError 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

StatusMeaningSolution
200Success-
204No Content (delete successful)-
400Bad RequestCheck request parameters and format
401UnauthorizedVerify API key
403ForbiddenInvoice doesn’t belong to your organization
404Not FoundCheck resource ID
422Validation ErrorReview error details in response
500Server ErrorContact support if persists

​
Error Response Format

{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

​
Use Cases

​
Track Electricity Consumption

Monitor electricity invoices for Scope 2 reporting: 
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: 
# 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")

Scope 1 & 2 Guide

Complete tutorial for tracking Scope 1 and 2 emissions

Facilities API

Manage facility data

Authentication Guide

Learn how to authenticate API requests

Custom Emission Factors

Create custom emission factors