Get Invoice

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/invoices/{invoice_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/invoices/{invoice_id}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "id": "<string>",
  "type": "<string>",
  "quantity": 123,
  "base_quantity": 123,
  "percentage": 123,
  "status": "<string>",
  "co2e": 123,
  "co2e_biomass": 123,
  "start_date": {},
  "end_date": {},
  "unit_id": {},
  "facility_id": {},
  "uploaded_by": {},
  "invoice_id": {},
  "cups": {},
  "file_id": {},
  "file_url": {},
  "enabled": {},
  "created_at": {},
  "updated_at": {},
  "base_total_spend": {},
  "total_spend": {},
  "currency_unit_id": {},
  "user": {
    "id": "<string>",
    "first_name": {},
    "last_name": {},
    "email": {},
    "prefix": {},
    "phone_number": {},
    "onboarding_done": {},
    "profile_img_url": {}
  },
  "facility_percentages": {
    "organization_id": "<string>",
    "facility_id": "<string>",
    "percentage": 123,
    "company_name": "<string>",
    "facility_name": "<string>"
  }
}

GET

invoices

{invoice_id}

Get Invoice

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/invoices/{invoice_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/invoices/{invoice_id}"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "id": "<string>",
  "type": "<string>",
  "quantity": 123,
  "base_quantity": 123,
  "percentage": 123,
  "status": "<string>",
  "co2e": 123,
  "co2e_biomass": 123,
  "start_date": {},
  "end_date": {},
  "unit_id": {},
  "facility_id": {},
  "uploaded_by": {},
  "invoice_id": {},
  "cups": {},
  "file_id": {},
  "file_url": {},
  "enabled": {},
  "created_at": {},
  "updated_at": {},
  "base_total_spend": {},
  "total_spend": {},
  "currency_unit_id": {},
  "user": {
    "id": "<string>",
    "first_name": {},
    "last_name": {},
    "email": {},
    "prefix": {},
    "phone_number": {},
    "onboarding_done": {},
    "profile_img_url": {}
  },
  "facility_percentages": {
    "organization_id": "<string>",
    "facility_id": "<string>",
    "percentage": 123,
    "company_name": "<string>",
    "facility_name": "<string>"
  }
}

Get Invoice

Retrieve detailed information about a specific invoice using its unique identifier. The response shape varies based on the invoice type field (discriminated union).

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Path Parameters

string

required

The unique identifier (UUID) of the invoice to retrieveExample: 550e8400-e29b-41d4-a716-446655440000

Response

The response is a discriminated union based on the type field. All invoice types share common fields, with additional fields depending on the type.

Common Fields

string

Unique identifier (UUID) for the invoice

string

Invoice type that determines the response shapeAvailable values: heat, electricity, water, recharge, process

number

Consumption amount after facility allocation

number

Original consumption amount before facility allocation

number

Facility allocation percentage (0-1)

string

Current invoice statusAvailable values: uploaded, loading, active, inactive, review, error

number

Calculated CO2 equivalent emissions (kg)

number

CO2 equivalent biomass emissions (kg)

datetime

Billing period start date

datetime

Billing period end date

string | null

Unit of measurement UUID

string | null

Associated facility UUID

string | null

UUID of the user who uploaded the invoice

string | null

External invoice identifier from the utility provider

string | null

CUPS code (for Spanish electricity supply points)

string | null

UUID of the linked file (if created via bulk import or PDF upload)

string | null

URL to download the linked file

boolean | null

Whether the invoice is enabled

datetime

Timestamp when the invoice was created

datetime | null

Timestamp when the invoice was last updated

number | null

Total spend before facility allocation (in the invoice currency)

number | null

Total spend after facility allocation

string | null

UUID of the currency unit for spend fields

object | null

User who uploaded the invoice

Show User Object

string

User UUID

string | null

First name

string | null

Last name

string | null

Email address

string | null

Phone prefix

string | null

Phone number

boolean | null

Whether onboarding is complete

string | null

Profile image URL

array[object] | null

Facility percentage allocations

Show Facility Percentage Object

string

The organization UUID

string

The facility UUID

number

The percentage allocation (0-1)

string

The company name

string

The facility name

Type-Specific Fields

The following fields are included depending on the invoice type:

Field	Types	Description
`supplier_id`	`heat`, `electricity`, `recharge`	Energy supplier UUID
`facility_fuel_id`	`heat`, `recharge`	Fuel type UUID
`stationary_fuel_id`	`heat`, `recharge`	Stationary fuel UUID
`stationary_fuel`	`heat`, `recharge`	Stationary fuel object (`id`, `name`)
`refrigerant_fuel_id`	`recharge`	Refrigerant fuel UUID
`refrigerant_fuel`	`recharge`	Refrigerant fuel object (`id`, `name`)
`self_consumption`	`electricity`	Whether this is a self-consumption invoice
`custom_emission_factor_id`	`heat`, `electricity`, `recharge`	Custom emission factor UUID
`custom_emission_factor`	`heat`, `electricity`, `recharge`	Custom emission factor details (object)

Example

curl -X GET "https://api.dcycle.io/v1/invoices/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

invoice_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    f"https://api.dcycle.io/v1/invoices/{invoice_id}",
    headers=headers
)

invoice = response.json()
print(f"Type: {invoice['type']}")
print(f"Quantity: {invoice['quantity']} (base: {invoice['base_quantity']})")
print(f"CO2e: {invoice['co2e']} kg")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

const invoiceId = '550e8400-e29b-41d4-a716-446655440000';

axios.get(
  `https://api.dcycle.io/v1/invoices/${invoiceId}`,
  { headers }
)
.then(response => {
  const invoice = response.data;
  console.log(`Type: ${invoice.type}`);
  console.log(`Quantity: ${invoice.quantity} (base: ${invoice.base_quantity})`);
  console.log(`CO2e: ${invoice.co2e} kg`);
})
.catch(error => console.error(error));

Successful Response

Electricity invoice example:

{
  "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",
  "facility_id": "660e8400-e29b-41d4-a716-446655440000",
  "uploaded_by": "990e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "INV-2024-001",
  "cups": "ES0021000000000001XX",
  "file_id": null,
  "file_url": "https://storage.dcycle.io/invoices/invoice-2024-001.pdf",
  "enabled": true,
  "created_at": "2024-02-01T10:30:00Z",
  "updated_at": "2024-02-01T10:30:00Z",
  "base_total_spend": 285.50,
  "total_spend": 142.75,
  "currency_unit_id": "eur-uuid",
  "user": {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "first_name": "Ana",
    "last_name": "García",
    "email": "ana@company.com",
    "prefix": null,
    "phone_number": null,
    "onboarding_done": true,
    "profile_img_url": 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",
  "self_consumption": false,
  "custom_emission_factor_id": null,
  "custom_emission_factor": null
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active.

404 Not Found

Cause: Invoice not found or doesn’t belong to your organization

{
  "detail": "Invoice not found",
  "code": "INVOICE_NOT_FOUND"
}

Solution: Verify the invoice ID exists and belongs to the organization specified in the header.

422 Validation Error

Cause: Invalid invoice ID format

{
  "detail": [
    {
      "loc": ["path", "invoice_id"],
      "msg": "value is not a valid uuid",
      "type": "type_error.uuid"
    }
  ]
}

Solution: Ensure the invoice ID is a valid UUID format.

Use Cases

Check Invoice Emissions by Type

def get_invoice_emissions(invoice_id):
    """Get invoice and display type-specific emissions info"""
    response = requests.get(
        f"https://api.dcycle.io/v1/invoices/{invoice_id}",
        headers=headers
    )

    invoice = response.json()
    inv_type = invoice["type"]

    print(f"Type: {inv_type}")
    print(f"CO2e: {invoice['co2e']} kg")
    print(f"CO2e biomass: {invoice['co2e_biomass']} kg")

    if inv_type in ("heat", "electricity", "recharge") and invoice.get("custom_emission_factor"):
        print(f"Custom EF: {invoice['custom_emission_factor']}")

    return invoice

invoice = get_invoice_emissions("550e8400-e29b-41d4-a716-446655440000")

Verify Facility Allocation

def check_facility_allocation(invoice_id):
    """Check how an invoice is allocated across facilities"""
    response = requests.get(
        f"https://api.dcycle.io/v1/invoices/{invoice_id}",
        headers=headers
    )
    invoice = response.json()

    if invoice.get("facility_percentages"):
        for alloc in invoice["facility_percentages"]:
            print(f"{alloc['facility_name']} ({alloc['company_name']}): {alloc['percentage'] * 100}%")
    else:
        print(f"Single facility: {invoice.get('facility_id')}")

check_facility_allocation("550e8400-e29b-41d4-a716-446655440000")

List Invoices

Retrieve all invoices with filtering

Update Invoice

Modify invoice details

Delete Invoice

Remove an invoice

Invoices Overview

Learn about the Invoices API

​Get Invoice

​Request

​Headers

​Path Parameters

​Response

​Common Fields

​Type-Specific Fields

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Check Invoice Emissions by Type

​Verify Facility Allocation

​Related Endpoints

List Invoices

Update Invoice

Delete Invoice

Invoices Overview

Get Invoice

Request

Headers

Path Parameters

Response

Common Fields

Type-Specific Fields

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Check Invoice Emissions by Type

Verify Facility Allocation

Related Endpoints