Update Invoice

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uploaded_by: '<string>',
    facility_id: '<string>',
    supplier_id: '<string>',
    refrigerant_fuel_id: '<string>',
    status: '<string>',
    invoice_id: '<string>',
    cups: '<string>',
    enabled: true,
    self_consumption: true
  })
};

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

payload = {
    "uploaded_by": "<string>",
    "facility_id": "<string>",
    "supplier_id": "<string>",
    "refrigerant_fuel_id": "<string>",
    "status": "<string>",
    "invoice_id": "<string>",
    "cups": "<string>",
    "enabled": True,
    "self_consumption": True
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/invoices/{invoice_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "uploaded_by": "<string>",
  "facility_id": "<string>",
  "supplier_id": "<string>",
  "refrigerant_fuel_id": "<string>",
  "status": "<string>",
  "invoice_id": "<string>",
  "cups": "<string>",
  "enabled": true,
  "self_consumption": true
}
'

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

PATCH

invoices

{invoice_id}

Update Invoice

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uploaded_by: '<string>',
    facility_id: '<string>',
    supplier_id: '<string>',
    refrigerant_fuel_id: '<string>',
    status: '<string>',
    invoice_id: '<string>',
    cups: '<string>',
    enabled: true,
    self_consumption: true
  })
};

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

payload = {
    "uploaded_by": "<string>",
    "facility_id": "<string>",
    "supplier_id": "<string>",
    "refrigerant_fuel_id": "<string>",
    "status": "<string>",
    "invoice_id": "<string>",
    "cups": "<string>",
    "enabled": True,
    "self_consumption": True
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/invoices/{invoice_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "uploaded_by": "<string>",
  "facility_id": "<string>",
  "supplier_id": "<string>",
  "refrigerant_fuel_id": "<string>",
  "status": "<string>",
  "invoice_id": "<string>",
  "cups": "<string>",
  "enabled": true,
  "self_consumption": true
}
'

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

Update Invoice

Updates an existing invoice with the provided fields. This is a partial update (PATCH), meaning only the fields included in the request body will be modified.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Path Parameters

UUID

required

The unique identifier of the invoice to update.Example: 550e8400-e29b-41d4-a716-446655440000

Body

UUID

ID of the user who uploaded the invoice.

UUID

ID of the facility to associate with this invoice.

UUID

ID of the energy supplier.

UUID

ID of an existing refrigerant gas for a recharge invoice.

string

Invoice status.Allowed values: uploaded, loading, active, inactive, review, error

string

Invoice number/identifier from the utility provider.

string

CUPS code for electricity invoices (Spanish market).

boolean

Whether the invoice is enabled and included in emission calculations.

boolean

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

Response

Returns a lightweight confirmation with core invoice fields. Use GET /v1/invoices/ for the full detail view.

string

UUID of the invoice

string

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

string

Invoice status: uploaded, loading, active, inactive, review, or error

string | null

UUID of the associated facility

string | null

UUID of the user who uploaded the invoice

string | null

UUID of the energy supplier

string | null

Invoice number/identifier from the utility provider

string | null

CUPS code for electricity invoices (Spanish market)

boolean | null

Whether the invoice is enabled and included in calculations

boolean | null

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

Example

curl -X PATCH "https://api.dcycle.io/v1/invoices/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "invoice_id": "INV-2024-001-UPDATED"
  }'

import requests
import os

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

response = requests.patch(
    f"https://api.dcycle.io/v1/invoices/{invoice_id}",
    headers={
        "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
        "x-api-key": os.getenv("DCYCLE_API_KEY"),
        "Content-Type": "application/json",
    },
    json={
        "status": "active",
        "invoice_id": "INV-2024-001-UPDATED",
    },
)

updated_invoice = response.json()
print(f"Invoice updated: {updated_invoice['id']}")

const axios = require('axios');

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

const response = await axios.patch(
  `https://api.dcycle.io/v1/invoices/${invoiceId}`,
  {
    status: 'active',
    invoice_id: 'INV-2024-001-UPDATED',
  },
  {
    headers: {
      'x-organization-id': process.env.DCYCLE_ORG_ID,
      'x-api-key': process.env.DCYCLE_API_KEY,
      'Content-Type': 'application/json',
    },
  }
);

console.log(`Invoice updated: ${response.data.id}`);

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "electricity",
  "status": "active",
  "facility_id": "660e8400-e29b-41d4-a716-446655440000",
  "uploaded_by": "990e8400-e29b-41d4-a716-446655440000",
  "supplier_id": "770e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "INV-2024-001-UPDATED",
  "cups": "ES0021000000000001XX",
  "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 invoice does not belong to the specified organization

{
  "detail": "Invoice does not belong to this organization",
  "code": "INVOICE_ACCESS_DENIED"
}

404 Not Found

Cause: No invoice exists with the given ID

{"detail": "Invoice not found"}

422 Validation Error

Cause: Invalid field values in the request body (e.g. unknown status)

{
  "detail": [
    {
      "loc": ["body", "status"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum"
    }
  ]
}

422 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"
}

Get Invoice

Get a single invoice by ID

List Invoices

Retrieve all invoices with filtering

Delete Invoice

Remove an invoice

Recalculate

Recalculate emissions for invoices

​Update Invoice

​Request

​Headers

​Path Parameters

​Body

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​422 Refrigerant Fuel Not Found

​Related Endpoints

Get Invoice

List Invoices

Delete Invoice

Recalculate

Update Invoice

Request

Headers

Path Parameters

Body

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

422 Refrigerant Fuel Not Found

Related Endpoints