Skip to main content

​
Invoices API

The Invoices API allows you to retrieve, update, and delete invoice records for tracking Scope 1 (direct emissions) and Scope 2 (indirect emissions from purchased energy) emissions. Invoices track energy consumption from various sources including electricity, natural gas, fuel deliveries, and water.
GHG Protocol Scope 1 & 2Invoices cover emissions from energy consumption at your facilities:
  • Scope 1: Direct emissions from fuel combustion (natural gas, fuel deliveries)
  • Scope 2: Indirect emissions from purchased electricity
This API helps you manage the data needed for accurate Scope 1 and 2 reporting.

​
Key Features

  • Invoice Management: Retrieve and manage invoice records
  • Multiple Invoice Types: Support for electricity, heat (natural gas, fuel delivery), and water
  • Facility Association: Link invoices to specific facilities for accurate emissions allocation
  • Filtering & Pagination: Efficiently query large invoice datasets
  • CO2e Tracking: View calculated emissions for each invoice

​
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

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: 
{
  "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,
  "cups": "ES0021000000000001XX",
  "created_at": "2024-02-01T10:30:00Z",
  "updated_at": "2024-02-01T10:30:00Z"
}

​
Invoice Attributes

FieldTypeDescription
idUUIDUnique identifier for the invoice
typestringInvoice type: heat, electricity, water, recharge
statusstringInvoice status (see Status Types)
quantityfloatConsumption amount
base_quantityfloatBase quantity before facility allocation
unit_idUUIDUnit of measurement
start_datedatetimeBilling period start date
end_datedatetimeBilling period end date
invoice_idstringInvoice number from the utility provider
facility_idUUIDAssociated facility
facility_fuel_idUUIDFuel type (for combustion invoices)
supplier_idUUIDEnergy supplier
custom_emission_factor_idUUIDCustom emission factor (if applicable)
co2efloatCalculated CO2 equivalent emissions (kg)
co2e_biomassfloatCO2e from biomass sources (kg)
cupsstringCUPS code (for Spanish electricity)
file_idUUIDLinked file/document ID
file_urlstringURL to download linked file
uploaded_byUUIDUser who uploaded the invoice
percentagefloatFacility allocation percentage (0-1)
enabledbooleanWhether invoice is enabled
created_atdatetimeWhen the invoice was created
updated_atdatetimeWhen the invoice was last updated

​
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

​
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 × Grid emission factor (kg CO2e/kWh)

​
Heat/Combustion (Scope 1)

CO2e = Fuel quantity × Fuel 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"], "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