Update Invoice

Update an existing invoice

PATCH /v1/invoices/{invoice_id}

Update Invoice

JavaScript

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));

200

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

← Invoices API

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

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

invoice_id · UUID · required

The unique identifier of the invoice to update.

Example: 550e8400-e29b-41d4-a716-446655440000

Body

uploaded_by · UUID

ID of the user who uploaded the invoice.

facility_id · UUID

ID of the facility to associate with this invoice.

Retrieve available options from GET /v1/facilities

supplier_id · UUID

ID of the energy supplier.

Retrieve available options from GET /api/v1/suppliers — electricity and energy suppliers

refrigerant_fuel_id · UUID

ID of an existing refrigerant gas for a recharge invoice.

status · string

Invoice status.

Allowed values: uploaded, loading, active, inactive, review, error

invoice_id · string

Invoice number/identifier from the utility provider.

cups · string

CUPS code for electricity invoices (Spanish market).

enabled · boolean

Whether the invoice is enabled and included in emission calculations.

self_consumption · boolean

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

Response

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

id · string

UUID of the invoice

type · string

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

status · string

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

facility_id · string | null

UUID of the associated facility

uploaded_by · string | null

UUID of the user who uploaded the invoice

supplier_id · string | null

UUID of the energy supplier

invoice_id · string | null

Invoice number/identifier from the utility provider

cups · string | null

CUPS code for electricity invoices (Spanish market)

enabled · boolean | null

Whether the invoice is enabled and included in calculations

self_consumption · boolean | null

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

Example

cURL

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

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

Related Endpoints

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