Skip to main content
GET
/
v3
/
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/v3/invoices/{invoice_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "<string>",
  "type": "<string>",
  "quantity": 123,
  "base_quantity": 123,
  "percentage": 123,
  "status": "<string>",
  "co2e": 123,
  "co2e_biomass": 123,
  "start_date": {},
  "end_date": {},
  "unit_id": {},
  "original_quantity": {},
  "original_unit_id": {},
  "facility_id": {},
  "uploaded_by": {},
  "invoice_id": {},
  "cups": {},
  "file_url": {},
  "source_invoice_id": {},
  "enabled": {},
  "created_at": {},
  "updated_at": {},
  "toc_id": {},
  "invofox_id": {},
  "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

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

​
Path Parameters

​
invoice_id
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

​
id
string
Unique identifier (UUID) for the invoice
​
type
string
Invoice type that determines the response shapeAvailable values: heat, electricity, water, recharge, process
​
quantity
number
Consumption amount after facility allocation
​
base_quantity
number
Original consumption amount before facility allocation
​
percentage
number
Facility allocation percentage (0-1)
​
status
string
Current invoice statusAvailable values: uploaded, loading, active, inactive, review, error
​
co2e
number
Calculated CO2 equivalent emissions (kg)
​
co2e_biomass
number
CO2 equivalent biomass emissions (kg)
​
start_date
datetime
Billing period start date
​
end_date
datetime
Billing period end date
​
unit_id
string | null
Unit of measurement ID
​
original_quantity
number | null
The original quantity before any conversions
​
original_unit_id
string | null
The original unit ID before any conversions
​
facility_id
string | null
Associated facility UUID
​
uploaded_by
string | null
UUID of the user who uploaded the invoice
​
invoice_id
string | null
External invoice identifier from the utility provider
​
cups
string | null
CUPS code (for Spanish electricity supply points)
​
file_url
string | null
URL to download the linked file
​
source_invoice_id
string | null
Source invoice UUID (if derived from another invoice)
​
enabled
boolean | null
Whether the invoice is enabled
​
created_at
datetime | null
Timestamp when the invoice was created
​
updated_at
datetime | null
Timestamp when the invoice was last updated
​
toc_id
string | null
The TOC ID
​
invofox_id
string | null
The Invofox integration ID
​
facility_percentages
array[object] | null
Facility percentage allocations

​
Type-Specific Fields

The following fields are included depending on the invoice type:
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

​
Example

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

​
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",
  "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
}

​
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/v3/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/v3/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