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

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

Show Facility Percentage Object

organization_id

string

The organization UUID

facility_id

string

The facility UUID

percentage

number

The percentage allocation (0-1)

company_name

string

The company name

facility_name

string

The facility name

Type-Specific Fields

The following fields are included depending on the invoice type:

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

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

Introduction

Organizations

Emissions

Projects

Facilities

Logistic Hubs

Vehicles

Unknown Vehicles

Vehicle Fuels

Logistics

Business Travels

Employees

Commuting Periods

Invoices

Purchases

Get Invoice

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

List Invoices

Update Invoice

Delete Invoice

Invoices Overview

Introduction

Organizations

Emissions

Projects

Facilities

Logistic Hubs

Vehicles

Unknown Vehicles

Vehicle Fuels

Logistics

Business Travels

Employees

Commuting Periods

Invoices

Purchases

​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