Invoices API - Dcycle Platform Docs

The Invoices API lets you send, read, update and delete the invoices of what a facility consumes: electricity, fuels burned on site (natural gas, diesel…), refrigerant gas recharged, water, heat or cold bought from a district network, and industrial process emissions. Dcycle calculates the emissions of every invoice. To send invoices, use the v2 route of their kind (see which route to use): up to 5,000 per request, each route taking only the fields that kind of invoice has. To read or update them one by one, use the /v1/invoices routes below; they see the invoices sent through v2 too. To delete them, of any kind, use POST /v2/invoices/delete.

GHG Protocol — Multiple ScopesInvoices cover emissions across multiple GHG Protocol scopes:

Scope 1: direct emissions: fuel burned on site (heat), refrigerant gas that leaked and was recharged (recharge) and industrial processes (process)
Scope 2: indirect emissions of energy bought: electricity and district heating or cooling (district_heat_and_steam)
Scope 3: the upstream of fuels (well-to-tank), the generation and transmission & distribution of electricity and of district heating or cooling, and water

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, district_heat_and_steam)
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: electricity, fuels, refrigerants, water, district heating and cooling, and process emissions

Which route to use

Each kind of consumption has its own v2 create route. The table also says how v1 stores it (type), which units it takes and which activity_categories a custom emission factor record needs to be usable on it.

You have an invoice of…	Send it to	Stored as `type`	Units	Custom factor category	Ids you need
Electricity from the grid	`POST /v2/invoices/electricity`	`electricity`	kWh	`electricity`	supplier: List Suppliers
Fuel burned on site (natural gas, diesel, LPG, biomass…)	`POST /v2/invoices/fuels`	`heat`	`GET /v2/units?type=stationary_combustion`	`stationary`	fuel: List Stationary Fuels
Refrigerant gas recharged (air conditioning, cold rooms)	`POST /v2/invoices/refrigerants`	`recharge`	kg	`recharge`	gas: List Refrigerant Gases
Mains water	`POST /v2/invoices/water`	`water`	`GET /v2/units?type=water`	`water`	—
Heat or steam from a district network	`POST /v2/invoices/district-heating`	`district_heat_and_steam` (`heat_cooling_type: heat`)	kWh, MWh, MJ, GJ	`heat_and_steam`	supplier (optional, for reference): List Suppliers
Chilled water from a district network	`POST /v2/invoices/district-cooling`	`district_heat_and_steam` (`heat_cooling_type: cooling`)	kWh, MWh, MJ, GJ	`cooling`	supplier (optional, for reference): List Suppliers
An industrial process (with your own factor)	`POST /v2/invoices/process`	`process`	`GET /v2/units?type=process`	`process`	your custom factor record (required)

Every route also needs the facilities and the unit: facility_percentages lists each facility (an id from List Facilities) with its share of the invoice, [{"facility_id": "...", "percentage": 1}] when it is all one facility’s, and unit_id comes from List Units.

Sending invoices (v2)

The v2 routes share one contract, the bulk ingest API (see how bulk ingestion works):

Send 1 to 5,000 invoices in records, with an Idempotency-Key header. Every record is checked first: if any is invalid the whole request is rejected (422 BULK_RECORDS_REJECTED: rejected is the number of invalid records and errors lists them, up to 100) and nothing is written. ?dry_run=true runs the checks only.
The answer is 202 Accepted with an ingest job: the invoices are already written (status loading), and the job calculates their emissions in the background.
Follow the job with GET /v2/ingest-jobs/{id}, or, for a job submitted with an API key, receive the ingest_job.finished webhook when it ends.
Read the outcome per record with GET /v2/ingest-jobs/{id}/items: each item has the invoice id (entity_id) and, if it could not be calculated, an error_code. Then read the invoices and their emissions with List Invoices.

To delete invoices of any kind in bulk, use POST /v2/invoices/delete, which works the same way.

Authentication

All endpoints require authentication using an API key included in the x-api-key header (see Authentication).

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 Electricity Invoices (v2)

Up to 5,000 electricity invoices per request, only the fields electricity needs

Create Fuel Invoices (v2)

Up to 5,000 fuel (stationary combustion) invoices per request

Create Refrigerant Invoices (v2)

Up to 5,000 refrigerant recharges (fugitive emissions) per request

Create Water Invoices (v2)

Up to 5,000 water invoices per request

Create District Heating Invoices (v2)

Up to 5,000 district heating invoices per request

Create District Cooling Invoices (v2)

Up to 5,000 district cooling invoices per request

Create Process Invoices (v2)

Up to 5,000 process emissions per request, with your own emission factor

Delete Invoices (v2)

Delete invoices of any category, asynchronously

Create Invoice (v1, deprecated)

Superseded by the v2 route of each kind of invoice

Update Invoice

Modify invoice details

Delete Invoice (v1, deprecated)

Superseded by Delete Invoices (v2)

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`, `district_heat_and_steam`
`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	For an invoice split across facilities, the id shared by all its per-facility invoices (the first one’s id)
`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
`stationary_fuel_id`	`heat`	Stationary fuel UUID
`refrigerant_fuel_id`	`recharge`	Refrigerant gas 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`	`electricity`, `district_heat_and_steam` (also `heat`, `water` from v1)	Energy supplier UUID
`self_consumption`	`electricity`	Electricity generated and consumed on site
`water_supply_point`, `water_meter_number`	`water`	Supply point (contract) and meter number
`heat_cooling_type`	`district_heat_and_steam`	`heat` (district heating) or `cooling` (district cooling)

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`	Fuel burned on site: natural gas, diesel, LPG, biomass… (stationary combustion)	Scope 1
`electricity`	Electricity bought from the grid	Scope 2
`water`	Mains water supplied	Scope 3
`recharge`	Refrigerant gas recharged: the fugitive emissions of what leaked	Scope 1
`process`	Industrial process emissions, with your own emission factor	Scope 1
`district_heat_and_steam`	Heat, steam (`heat_cooling_type: heat`) or chilled water (`cooling`) bought from a district network	Scope 2

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

The /v1/invoices routes answer errors as:

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

The /v2/invoices/* routes answer with problem details (application/problem+json), with one entry per invalid record in errors (up to 100; rejected is the number of invalid records).

Use Cases

Scope 1 and 2 emissions of your invoices

An invoice’s co2e adds every scope it has, scope 3 included. For the scope 1 or 2 part alone:

Electricity (scope 2, market-based), fuels (heat, scope 1) and district heating or cooling (scope 2): co2e_consumption of each invoice in List Invoices, or total_co2e_consumption of Totals for one facility and invoice type. The location-based scope 2 of electricity is co2e_location_based.
Refrigerants (recharge) and process: scope 1 whole, in co2e.
Water: scope 3 whole, in 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

Your own factors, usable on invoices with custom_ef_record_id

MCP Tools

Query invoice data from AI assistants via MCP

​Key Features

​Which route to use

​Sending invoices (v2)

​Authentication

​Headers

​Available Endpoints

List Invoices

Get Invoice

Create Electricity Invoices (v2)

Create Fuel Invoices (v2)

Create Refrigerant Invoices (v2)

Create Water Invoices (v2)

Create District Heating Invoices (v2)

Create District Cooling Invoices (v2)

Create Process Invoices (v2)

Delete Invoices (v2)

Create Invoice (v1, deprecated)

Update Invoice

Delete Invoice (v1, deprecated)

​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

​Scope 1 and 2 emissions of your invoices

​Related Documentation