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 an API key included in the x-api-key header.

Headers

All requests must include:

string

required

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

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

Create Invoice

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

Field	Type	Description
`id`	UUID	Unique identifier for the invoice
`type`	string	Invoice type: `heat`, `electricity`, `water`, `recharge`, `process`
`quantity`	float	Consumption amount after facility allocation
`base_quantity`	float	Original consumption amount before facility allocation
`percentage`	float	Facility allocation percentage (0-1)
`status`	string	Invoice status (see Status Types)
`co2e`	float	Calculated CO2 equivalent emissions (kg)
`co2e_biomass`	float	CO2e from biomass sources (kg)
`start_date`	datetime	Billing period start date
`end_date`	datetime	Billing period end date
`unit_id`	UUID	Unit of measurement
`original_quantity`	float	Original quantity before conversions
`original_unit_id`	UUID	Original unit before conversions
`facility_id`	UUID	Associated facility
`uploaded_by`	UUID	User who uploaded the invoice
`invoice_id`	string	External invoice identifier from utility provider
`cups`	string	CUPS code (for Spanish electricity)
`file_url`	string	URL to download linked file
`source_invoice_id`	UUID	Source invoice (if derived from another invoice)
`enabled`	boolean	Whether invoice is enabled
`created_at`	datetime	When the invoice was created
`updated_at`	datetime	When the invoice was last updated
`toc_id`	UUID	TOC identifier
`invofox_id`	string	Invofox integration ID
`facility_percentages`	array	Facility percentage allocations (see below)

Type-Specific Fields

Field	Types	Description
`facility_fuel_id`	`heat`, `recharge`	Fuel type UUID
`custom_emission_factor_id`	`heat`, `electricity`, `recharge`	Custom emission factor UUID
`custom_emission_factor`	`heat`, `electricity`, `recharge`	Custom emission factor details (object)
`supplier_id`	`heat`, `electricity`, `recharge`	Energy supplier UUID

Facility Percentage Object

Field	Type	Description
`organization_id`	UUID	Organization UUID
`facility_id`	UUID	Facility UUID
`percentage`	float	Allocation percentage (0-1)
`company_name`	string	Company name
`facility_name`	string	Facility name

Invoice Types

Type	Description	GHG Scope
`heat`	Natural gas and fuel delivery invoices	Scope 1
`electricity`	Electricity consumption invoices	Scope 2
`water`	Water consumption invoices	Scope 3 (if applicable)
`recharge`	Electric vehicle recharging	Scope 2
`process`	Industrial process emissions	Scope 1

Status Types

Status	Description
`uploaded`	Invoice uploaded, awaiting processing
`loading`	Invoice being processed
`active`	Invoice active and included in calculations
`inactive`	Invoice inactive (excluded from calculations)
`review`	Invoice under review
`error`	Error 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

Status	Meaning	Solution
200	Success	-
204	No Content (delete successful)	-
400	Bad Request	Check request parameters and format
401	Unauthorized	Verify API key
403	Forbidden	Invoice doesn’t belong to your organization
404	Not Found	Check resource ID
422	Validation Error	Review error details in response
500	Server Error	Contact 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

MCP Tools

Query invoice data from AI assistants via MCP

Calculation Steps List Invoices

​Invoices API

​Key Features

​Authentication

​Headers

​Available Endpoints

List Invoices

Get Invoice

Create Invoice

Update Invoice

Delete Invoice

​Data Model

​Invoice Object

​Invoice Attributes

​Type-Specific Fields

​Facility Percentage Object

​Invoice Types

​Status Types

​CO2e Calculation

​Electricity (Scope 2)

​Heat/Combustion (Scope 1)

​Process (Scope 1)

​Error Handling

​Common HTTP Status Codes

​Error Response Format

​Use Cases

​Track Electricity Consumption

​Calculate Scope 1 from Fuel Invoices

​Related Documentation