Create Invoice

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: '<string>',
    base_quantity: 123,
    unit_id: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    uploaded_by: '<string>',
    facility_percentages: [{}],
    facility_id: '<string>',
    invoice_id: '<string>',
    supplier_id: '<string>',
    stationary_fuel_id: '<string>',
    refrigerant_fuel_id: '<string>',
    cups: '<string>',
    file_url: '<string>',
    custom_emission_factor_id: '<string>',
    toc: '<string>'
  })
};

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

import requests

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

payload = {
    "type": "<string>",
    "base_quantity": 123,
    "unit_id": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "uploaded_by": "<string>",
    "facility_percentages": [{}],
    "facility_id": "<string>",
    "invoice_id": "<string>",
    "supplier_id": "<string>",
    "stationary_fuel_id": "<string>",
    "refrigerant_fuel_id": "<string>",
    "cups": "<string>",
    "file_url": "<string>",
    "custom_emission_factor_id": "<string>",
    "toc": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/invoices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "type": "<string>",
  "base_quantity": 123,
  "unit_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "uploaded_by": "<string>",
  "facility_percentages": [
    {}
  ],
  "facility_id": "<string>",
  "invoice_id": "<string>",
  "supplier_id": "<string>",
  "stationary_fuel_id": "<string>",
  "refrigerant_fuel_id": "<string>",
  "cups": "<string>",
  "file_url": "<string>",
  "custom_emission_factor_id": "<string>",
  "toc": "<string>"
}
'

{
  "id": "<string>",
  "type": "<string>",
  "status": "<string>",
  "facility_id": {},
  "uploaded_by": {},
  "supplier_id": {},
  "invoice_id": {},
  "cups": {},
  "enabled": {},
  "self_consumption": {}
}

POST

invoices

Create Invoice

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: '<string>',
    base_quantity: 123,
    unit_id: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    uploaded_by: '<string>',
    facility_percentages: [{}],
    facility_id: '<string>',
    invoice_id: '<string>',
    supplier_id: '<string>',
    stationary_fuel_id: '<string>',
    refrigerant_fuel_id: '<string>',
    cups: '<string>',
    file_url: '<string>',
    custom_emission_factor_id: '<string>',
    toc: '<string>'
  })
};

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

import requests

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

payload = {
    "type": "<string>",
    "base_quantity": 123,
    "unit_id": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "uploaded_by": "<string>",
    "facility_percentages": [{}],
    "facility_id": "<string>",
    "invoice_id": "<string>",
    "supplier_id": "<string>",
    "stationary_fuel_id": "<string>",
    "refrigerant_fuel_id": "<string>",
    "cups": "<string>",
    "file_url": "<string>",
    "custom_emission_factor_id": "<string>",
    "toc": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/invoices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "type": "<string>",
  "base_quantity": 123,
  "unit_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "uploaded_by": "<string>",
  "facility_percentages": [
    {}
  ],
  "facility_id": "<string>",
  "invoice_id": "<string>",
  "supplier_id": "<string>",
  "stationary_fuel_id": "<string>",
  "refrigerant_fuel_id": "<string>",
  "cups": "<string>",
  "file_url": "<string>",
  "custom_emission_factor_id": "<string>",
  "toc": "<string>"
}
'

{
  "id": "<string>",
  "type": "<string>",
  "status": "<string>",
  "facility_id": {},
  "uploaded_by": {},
  "supplier_id": {},
  "invoice_id": {},
  "cups": {},
  "enabled": {},
  "self_consumption": {}
}

Create Invoice

Create a new consumption invoice (electricity, heat, water, etc.) for your organization. This endpoint supports both single-facility invoices and distributed invoices (split across multiple facilities with percentage allocation).

This endpoint automatically calculates CO2e emissions based on the invoice type, quantity, and location. For distributed invoices, emissions are proportionally allocated across facilities.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

Body Parameters

string

required

Type of consumption invoiceValid values: electricity, heat, water, recharge, processExample: "electricity"

number

required

Consumption quantity in the specified unitExample: 15000.5

string

required

UUID of the unit of measurementCommon units:

Electricity: kilowatt_hour_(kwh)
Natural gas: cubic_meter_(m³)
Water: cubic_meter_(m³)
Diesel/Gasoline: liter_(l)

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

string

required

Invoice period start date (ISO 8601 format)Example: "2024-11-01"

string

required

Invoice period end date (ISO 8601 format)Example: "2024-11-30"

string

UUID of the user creating the invoice. Optional when using JWT authentication.Example: "b2c3d4e5-f6g7-8901-bcde-fg2345678901"

array

required

Array of facility allocation objects. Sum of percentages must equal 1.0 (100%)

Facility Percentage Object:

organization_id (string, UUID, required) - Organization that owns the facility
facility_id (string, UUID, required) - Facility to allocate to
percentage (number, required) - Allocation percentage (0.0-1.0)
company_name (string, optional) - Company name for reference
facility_name (string, optional) - Facility name for reference

Example:

[
  {
    "organization_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
    "facility_id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
    "percentage": 1.0,
    "company_name": "Acme Corp",
    "facility_name": "Madrid Office"
  }
]

For distributed invoices (multiple facilities):

[
  {
    "organization_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
    "facility_id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
    "percentage": 0.6,
    "company_name": "Acme Corp",
    "facility_name": "Madrid Office"
  },
  {
    "organization_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
    "facility_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
    "percentage": 0.4,
    "company_name": "Acme Corp",
    "facility_name": "Barcelona Office"
  }
]

string

deprecated

Deprecated: Use facility_percentages insteadLegacy single facility ID field. Maintained for backwards compatibility.

string

External invoice reference number (e.g., supplier invoice number)Example: "INV-2024-11-001"

string

UUID of the energy/utility supplierExample: "f6g7h8i9-j0k1-2345-fghi-jk6789012345"

string

UUID of the stationary fuel (for heat invoices)Example: "g7h8i9j0-k1l2-3456-ghij-kl7890123456"

string

UUID of an existing refrigerant gas for recharge invoices. An unknown UUID is rejected with 422 REFRIGERANT_FUEL_NOT_FOUND.

string

CUPS code for Spanish electricity metersFormat: ES + 20 digits + 2 letters (e.g., ES0031406398765432GH0F)Example: "ES0031406398765432GH0F"

string

URL to the invoice file (PDF, image, etc.) stored in S3Example: "https://s3.amazonaws.com/dcycle-files/invoices/..."

string

UUID of custom emission factor group (if using custom factors)Example: "h8i9j0k1-l2m3-4567-hijk-lm8901234567"

string

Transport operation category (for logistics-related invoices)Example: "van_diesel"

Response

The create endpoint returns a lightweight confirmation with the core invoice fields. Use GET /v1/invoices/ for the full detail view.

string

UUID of the created invoice

string

Invoice type: electricity, heat, water, recharge, or process

string

Invoice status: loading (processing), active (complete), or error (failed)

string | null

UUID of the primary facility

string | null

UUID of the user who created the invoice

string | null

UUID of the energy supplier, if specified

string | null

External invoice reference number

string | null

CUPS code, if specified

boolean | null

Whether the invoice is enabled for emission calculations

boolean | null

Whether this is a self-consumption invoice (electricity only)

Example

curl -X POST "https://api.dcycle.io/v1/invoices" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \

  -H "Content-Type: application/json" \
  -d '{
    "type": "electricity",
    "base_quantity": 15000,
    "unit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "start_date": "2024-11-01",
    "end_date": "2024-11-30",
    "uploaded_by": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
    "invoice_id": "E-2024-11-001",
    "cups": "ES0031406398765432GH0F",
    "supplier_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
    "facility_percentages": [
      {
        "organization_id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
        "facility_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
        "percentage": 1.0,
        "company_name": "Acme Corp",
        "facility_name": "Madrid Office"
      }
    ]
  }'

curl -X POST "https://api.dcycle.io/v1/invoices" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \

  -H "Content-Type: application/json" \
  -d '{
    "type": "heat",
    "base_quantity": 5000,
    "unit_id": "f6g7h8i9-j0k1-2345-fghi-jk6789012345",
    "start_date": "2024-11-01",
    "end_date": "2024-11-30",
    "uploaded_by": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
    "invoice_id": "H-2024-11-015",
    "stationary_fuel_id": "g7h8i9j0-k1l2-3456-ghij-kl7890123456",
    "facility_percentages": [
      {
        "organization_id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
        "facility_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
        "percentage": 0.6,
        "company_name": "Acme Corp",
        "facility_name": "Madrid Office"
      },
      {
        "organization_id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
        "facility_id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
        "percentage": 0.4,
        "company_name": "Acme Corp",
        "facility_name": "Barcelona Office"
      }
    ]
  }'

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,

    "Content-Type": "application/json"
}

invoice_data = {
    "type": "electricity",
    "base_quantity": 15000,
    "unit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "start_date": "2024-11-01",
    "end_date": "2024-11-30",
    "uploaded_by": user_id,
    "invoice_id": "E-2024-11-001",
    "cups": "ES0031406398765432GH0F",
    "supplier_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
    "facility_percentages": [
        {
            "organization_id": org_id,
            "facility_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
            "percentage": 1.0,
            "company_name": "Acme Corp",
            "facility_name": "Madrid Office"
        }
    ]
}

response = requests.post(
    "https://api.dcycle.io/v1/invoices",
    headers=headers,
    json=invoice_data
)

invoice = response.json()
print(f"Invoice created: {invoice['id']}")
print(f"Status: {invoice['status']}")
print(f"Quantity: {invoice['quantity']} kWh")

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,

    "Content-Type": "application/json"
}

# Shared heating bill split 60/40 between two facilities
invoice_data = {
    "type": "heat",
    "base_quantity": 5000,
    "unit_id": "f6g7h8i9-j0k1-2345-fghi-jk6789012345",
    "start_date": "2024-11-01",
    "end_date": "2024-11-30",
    "uploaded_by": user_id,
    "invoice_id": "H-2024-11-015",
    "stationary_fuel_id": "g7h8i9j0-k1l2-3456-ghij-kl7890123456",
    "facility_percentages": [
        {
            "organization_id": org_id,
            "facility_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
            "percentage": 0.6,
            "company_name": "Acme Corp",
            "facility_name": "Madrid Office"
        },
        {
            "organization_id": org_id,
            "facility_id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
            "percentage": 0.4,
            "company_name": "Acme Corp",
            "facility_name": "Barcelona Office"
        }
    ]
}

response = requests.post(
    "https://api.dcycle.io/v1/invoices",
    headers=headers,
    json=invoice_data
)

invoice = response.json()
print(f"Parent invoice created: {invoice['id']}")
print(f"Distributed across {len(invoice['facility_percentages'])} facilities")

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,

  'Content-Type': 'application/json'
};

const invoiceData = {
  type: 'electricity',
  base_quantity: 15000,
  unit_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  start_date: '2024-11-01',
  end_date: '2024-11-30',
  uploaded_by: userId,
  invoice_id: 'E-2024-11-001',
  cups: 'ES0031406398765432GH0F',
  supplier_id: 'c3d4e5f6-g7h8-9012-cdef-gh3456789012',
  facility_percentages: [
    {
      organization_id: orgId,
      facility_id: 'e5f6g7h8-i9j0-1234-efgh-ij5678901234',
      percentage: 1.0,
      company_name: 'Acme Corp',
      facility_name: 'Madrid Office'
    }
  ]
};

axios.post(
  'https://api.dcycle.io/v1/invoices',
  invoiceData,
  { headers }
)
.then(response => {
  const invoice = response.data;
  console.log(`Invoice created: ${invoice.id}`);
  console.log(`Status: ${invoice.status}`);
})
.catch(error => console.error(error));

Successful Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "electricity",
  "status": "loading",
  "facility_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
  "uploaded_by": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
  "supplier_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
  "invoice_id": "E-2024-11-001",
  "cups": "ES0031406398765432GH0F",
  "enabled": true,
  "self_consumption": false
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

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

403 Forbidden

Cause: The user is not a member of the organization, or lacks permission to create invoices for it

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

{"detail": "ORGANIZATION_ID_IS_NOT_UNDER_PARENT_ORGANIZATION", "code": "FORBIDDEN"}

400 Bad Request - Invalid Total Percentage

Cause: Sum of facility_percentages does not equal 1.0

{
  "detail": "INVALID_TOTAL_PERCENTAGE",
  "code": "VALIDATION_ERROR"
}

Solution: Ensure the sum of all percentage values in facility_percentages equals exactly 1.0 (100%).

400 Bad Request - Invalid Invoice Type

Cause: Unsupported invoice type

{
  "detail": "Bad invoice type: xyz. It must be one of ('heat', 'electricity', 'water', 'recharge', 'process')",
  "code": "VALIDATION_ERROR"
}

Solution: Use only valid invoice types: heat, electricity, water, recharge, process

400 Bad Request - Invalid Facility

Cause: Facility doesn’t belong to the specified organization or is archived

{
  "detail": "Bad facility_id: xxx. It must belong to the provided organization_id yyy",
  "code": "VALIDATION_ERROR"
}

Solution: Verify that:

The facility_id exists and belongs to the organization_id
The facility is not archived
You have access to the organization

404 Not Found - Organization Not Found

Cause: Organization ID in facility_percentages doesn’t exist

{
  "detail": "Bad organization_id: xxx. Organization not found",
  "code": "NOT_FOUND"
}

Solution: Use valid organization UUIDs that exist in the system.

422 Unprocessable Content - Refrigerant Fuel Not Found

Cause: refrigerant_fuel_id does not reference an existing refrigerant gas.

{
  "detail": "Refrigerant fuel with id=<uuid> not found",
  "code": "REFRIGERANT_FUEL_NOT_FOUND"
}

Solution: Use a valid refrigerant gas UUID.

Use Cases

Single Facility Electricity Invoice

Create an electricity invoice for one facility:

def create_electricity_invoice(facility_id, kwh, start_date, end_date, invoice_number):
    """Create electricity invoice for a single facility"""
    invoice_data = {
        "type": "electricity",
        "base_quantity": kwh,
        "unit_id": "kwh-unit-id",  # Get from units endpoint
        "start_date": start_date,
        "end_date": end_date,
        "uploaded_by": user_id,
        "invoice_id": invoice_number,
        "supplier_id": "supplier-id",  # Your electricity supplier
        "facility_percentages": [
            {
                "organization_id": org_id,
                "facility_id": facility_id,
                "percentage": 1.0
            }
        ]
    }

    response = requests.post(
        "https://api.dcycle.io/v1/invoices",
        headers=headers,
        json=invoice_data
    )

    return response.json()

# Example: Create invoice for 15,000 kWh
invoice = create_electricity_invoice(
    facility_id="facility-uuid",
    kwh=15000,
    start_date="2024-11-01",
    end_date="2024-11-30",
    invoice_number="E-2024-11-001"
)

Distributed Heat Invoice

Split a shared heating bill across multiple facilities:

def create_shared_heating_invoice(facilities, total_m3, start_date, end_date):
    """Create distributed heat invoice across facilities"""
    # Calculate percentages based on facility sizes
    total_size = sum(f['size_m2'] for f in facilities)

    facility_percentages = []
    for facility in facilities:
        percentage = facility['size_m2'] / total_size

        facility_percentages.append({
            "organization_id": org_id,
            "facility_id": facility['id'],
            "percentage": round(percentage, 4),  # Round to avoid floating point errors
            "facility_name": facility['name']
        })

    # Verify percentages sum to 1.0
    total_percentage = sum(f['percentage'] for f in facility_percentages)
    if abs(total_percentage - 1.0) > 0.0001:
        # Adjust last percentage to ensure exact 1.0
        facility_percentages[-1]['percentage'] += (1.0 - total_percentage)

    invoice_data = {
        "type": "heat",
        "base_quantity": total_m3,
        "unit_id": "m3-unit-id",
        "start_date": start_date,
        "end_date": end_date,
        "uploaded_by": user_id,
        "stationary_fuel_id": "natural-gas-id",
        "facility_percentages": facility_percentages
    }

    response = requests.post(
        "https://api.dcycle.io/v1/invoices",
        headers=headers,
        json=invoice_data
    )

    return response.json()

# Example: Shared heating across 3 facilities
facilities = [
    {"id": "facility-1-uuid", "name": "Building A", "size_m2": 1000},
    {"id": "facility-2-uuid", "name": "Building B", "size_m2": 1500},
    {"id": "facility-3-uuid", "name": "Building C", "size_m2": 500}
]

invoice = create_shared_heating_invoice(
    facilities=facilities,
    total_m3=5000,
    start_date="2024-11-01",
    end_date="2024-11-30"
)

Corporate Distribution

Headquarters distributing utility bills to subsidiaries:

def distribute_utility_to_subsidiaries(invoice_type, quantity, subsidiaries):
    """Distribute utility invoice across subsidiary organizations"""
    facility_percentages = []

    for subsidiary in subsidiaries:
        facility_percentages.append({
            "organization_id": subsidiary['org_id'],
            "facility_id": subsidiary['facility_id'],
            "percentage": subsidiary['cost_allocation'],
            "company_name": subsidiary['company_name'],
            "facility_name": subsidiary['facility_name']
        })

    invoice_data = {
        "type": invoice_type,
        "base_quantity": quantity,
        "unit_id": get_unit_id_for_type(invoice_type),
        "start_date": "2024-11-01",
        "end_date": "2024-11-30",
        "uploaded_by": user_id,
        "facility_percentages": facility_percentages
    }

    response = requests.post(
        "https://api.dcycle.io/v1/invoices",
        headers=headers,
        json=invoice_data
    )

    return response.json()

# Example: HQ distributing water bill to 3 subsidiaries
subsidiaries = [
    {
        "org_id": "subsidiary-1-org-id",
        "facility_id": "subsidiary-1-facility-id",
        "cost_allocation": 0.5,
        "company_name": "Subsidiary A",
        "facility_name": "Main Office"
    },
    {
        "org_id": "subsidiary-2-org-id",
        "facility_id": "subsidiary-2-facility-id",
        "cost_allocation": 0.3,
        "company_name": "Subsidiary B",
        "facility_name": "Regional Office"
    },
    {
        "org_id": "subsidiary-3-org-id",
        "facility_id": "subsidiary-3-facility-id",
        "cost_allocation": 0.2,
        "company_name": "Subsidiary C",
        "facility_name": "Branch Office"
    }
]

invoice = distribute_utility_to_subsidiaries(
    invoice_type="water",
    quantity=1000,
    subsidiaries=subsidiaries
)

Batch Invoice Creation

Create multiple invoices efficiently:

def create_monthly_invoices(facilities, month, year):
    """Create invoices for all facilities for a given month"""
    from datetime import datetime
    import calendar

    # Calculate month dates
    start_date = f"{year}-{month:02d}-01"
    last_day = calendar.monthrange(year, month)[1]
    end_date = f"{year}-{month:02d}-{last_day}"

    created_invoices = []

    for facility in facilities:
        invoice_data = {
            "type": "electricity",
            "base_quantity": facility['monthly_kwh'],
            "unit_id": "kwh-unit-id",
            "start_date": start_date,
            "end_date": end_date,
            "uploaded_by": user_id,
            "supplier_id": facility['supplier_id'],
            "facility_percentages": [
                {
                    "organization_id": org_id,
                    "facility_id": facility['id'],
                    "percentage": 1.0,
                    "facility_name": facility['name']
                }
            ]
        }

        try:
            response = requests.post(
                "https://api.dcycle.io/v1/invoices",
                headers=headers,
                json=invoice_data
            )
            created_invoices.append(response.json())
            print(f"✓ Created invoice for {facility['name']}")
        except Exception as e:
            print(f"✗ Failed for {facility['name']}: {str(e)}")

    return created_invoices

# Example: Create November 2024 invoices for all facilities
facilities = [
    {"id": "fac-1", "name": "Madrid Office", "monthly_kwh": 15000, "supplier_id": "sup-1"},
    {"id": "fac-2", "name": "Barcelona Office", "monthly_kwh": 12000, "supplier_id": "sup-1"},
    {"id": "fac-3", "name": "Valencia Office", "monthly_kwh": 8000, "supplier_id": "sup-2"}
]

invoices = create_monthly_invoices(facilities, month=11, year=2024)
print(f"Created {len(invoices)} invoices")

Special Notes

Invoice Status Workflow

Invoices go through the following status workflow:

loading: Initial state after creation. System is calculating emissions.
active: Processing complete. Emissions calculated and available.
error: Processing failed. Check error_messages field in GET response.

Typically, invoices move from loading to active within a few seconds.

Distributed Invoices

When creating distributed invoices (multiple facilities):

The system creates one parent invoice + N child invoices (one per facility)
The parent invoice ID is returned in the response
All child invoices reference the parent via source_invoice_id
Emissions are automatically calculated proportionally for each facility
Percentages must sum to exactly 1.0 (100%)

Use cases for distributed invoices:

Shared utility bills across office floors
Corporate headquarters allocating costs
Multi-tenant buildings
Franchise operations with centralized billing

Date Format

Dates must be provided in ISO 8601 format: YYYY-MM-DD Valid examples:

"2024-11-01"
"2024-12-31"

The system will handle timezone conversion based on facility location.

Invoice Types and Required Fields

Different invoice types have different requirements:

Type	Required Fields	Optional Fields
`electricity`	type, base_quantity, unit_id, dates, facility_percentages	supplier_id, cups, file_url
`heat`	type, base_quantity, unit_id, dates, facility_percentages	stationary_fuel_id, supplier_id, file_url
`water`	type, base_quantity, unit_id, dates, facility_percentages	supplier_id, file_url
`recharge`	type, base_quantity, unit_id, dates, facility_percentages	refrigerant_fuel_id, supplier_id, toc
`process`	type, base_quantity, unit_id, dates, facility_percentages	custom_emission_factor_id

Units

Common unit UUIDs for different consumption types:

Electricity: kilowatt_hour_(kwh)
Natural Gas: cubic_meter_(m³)
Diesel/Gasoline: liter_(l)
Water: cubic_meter_(m³)

Use the Units endpoint to get the complete list of available units and their UUIDs.

CUPS Validation

For Spanish electricity invoices, if you provide a cups code:

Format: ES + 20 digits + 2 letters
Example: ES0031406398765432GH0F
The system validates format but doesn’t verify existence with utility companies

Emission Calculation

CO2e emissions are calculated automatically based on:

Consumption quantity and unit
Facility location (country-specific emission factors)
Time period (emission factors vary by year/month)
Supplier (if renewable energy contract)
Custom emission factors (if specified)

For electricity, the system calculates:

Scope 2 (consumption) emissions
Scope 3 (generation + T&D) emissions

File Attachments

To attach invoice files (PDF, images):

Upload file to S3 using presigned URL (separate endpoint)
Include the S3 URL in file_url field
System will retain file for audit trail

List Invoices

Query created invoices

List Facilities

Get facility IDs for invoice creation

Authentication

Learn about API authentication

​Create Invoice

​Request

​Headers

​Body Parameters

​Facility Percentage Object:

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​400 Bad Request - Invalid Total Percentage

​400 Bad Request - Invalid Invoice Type

​400 Bad Request - Invalid Facility

​404 Not Found - Organization Not Found

​422 Unprocessable Content - Refrigerant Fuel Not Found

​Use Cases

​Single Facility Electricity Invoice

​Distributed Heat Invoice

​Corporate Distribution

​Batch Invoice Creation

​Special Notes

​Invoice Status Workflow

​Distributed Invoices

​Date Format

​Invoice Types and Required Fields

​Units

​CUPS Validation

​Emission Calculation

​File Attachments

​Related Endpoints

List Invoices

List Facilities

Authentication

Create Invoice

Request

Headers

Body Parameters

Facility Percentage Object:

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

400 Bad Request - Invalid Total Percentage

400 Bad Request - Invalid Invoice Type

400 Bad Request - Invalid Facility

404 Not Found - Organization Not Found

422 Unprocessable Content - Refrigerant Fuel Not Found

Use Cases

Single Facility Electricity Invoice

Distributed Heat Invoice

Corporate Distribution

Batch Invoice Creation

Special Notes

Invoice Status Workflow

Distributed Invoices

Date Format

Invoice Types and Required Fields

Units

CUPS Validation

Emission Calculation

File Attachments

Related Endpoints