Replace Invoice - Dcycle Platform Docs

Replace Invoice

const options = {
  method: 'PUT',
  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>',
    facility_id: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    facility_percentages: [{}],
    file_url: '<string>',
    file_name: '<string>',
    supplier_id: '<string>',
    invoice_id: '<string>',
    custom_ef_record_id: '<string>',
    water_supply_point: '<string>',
    water_meter_number: '<string>',
    base_total_spend: 123,
    currency_unit_id: '<string>',
    self_consumption: true,
    heat_cooling_type: '<string>'
  })
};

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 = {
    "type": "<string>",
    "base_quantity": 123,
    "unit_id": "<string>",
    "facility_id": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "facility_percentages": [{}],
    "file_url": "<string>",
    "file_name": "<string>",
    "supplier_id": "<string>",
    "invoice_id": "<string>",
    "custom_ef_record_id": "<string>",
    "water_supply_point": "<string>",
    "water_meter_number": "<string>",
    "base_total_spend": 123,
    "currency_unit_id": "<string>",
    "self_consumption": True,
    "heat_cooling_type": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request PUT \
  --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 '
{
  "type": "<string>",
  "base_quantity": 123,
  "unit_id": "<string>",
  "facility_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "facility_percentages": [
    {}
  ],
  "file_url": "<string>",
  "file_name": "<string>",
  "supplier_id": "<string>",
  "invoice_id": "<string>",
  "custom_ef_record_id": "<string>",
  "water_supply_point": "<string>",
  "water_meter_number": "<string>",
  "base_total_spend": 123,
  "currency_unit_id": "<string>",
  "self_consumption": true,
  "heat_cooling_type": "<string>"
}
'

PUT

invoices

{invoice_id}

Replace Invoice

const options = {
  method: 'PUT',
  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>',
    facility_id: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    facility_percentages: [{}],
    file_url: '<string>',
    file_name: '<string>',
    supplier_id: '<string>',
    invoice_id: '<string>',
    custom_ef_record_id: '<string>',
    water_supply_point: '<string>',
    water_meter_number: '<string>',
    base_total_spend: 123,
    currency_unit_id: '<string>',
    self_consumption: true,
    heat_cooling_type: '<string>'
  })
};

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 = {
    "type": "<string>",
    "base_quantity": 123,
    "unit_id": "<string>",
    "facility_id": "<string>",
    "start_date": "<string>",
    "end_date": "<string>",
    "facility_percentages": [{}],
    "file_url": "<string>",
    "file_name": "<string>",
    "supplier_id": "<string>",
    "invoice_id": "<string>",
    "custom_ef_record_id": "<string>",
    "water_supply_point": "<string>",
    "water_meter_number": "<string>",
    "base_total_spend": 123,
    "currency_unit_id": "<string>",
    "self_consumption": True,
    "heat_cooling_type": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

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

print(response.text)

curl --request PUT \
  --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 '
{
  "type": "<string>",
  "base_quantity": 123,
  "unit_id": "<string>",
  "facility_id": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "facility_percentages": [
    {}
  ],
  "file_url": "<string>",
  "file_name": "<string>",
  "supplier_id": "<string>",
  "invoice_id": "<string>",
  "custom_ef_record_id": "<string>",
  "water_supply_point": "<string>",
  "water_meter_number": "<string>",
  "base_total_spend": 123,
  "currency_unit_id": "<string>",
  "self_consumption": true,
  "heat_cooling_type": "<string>"
}
'

← Invoices API Replaces an invoice and its split across facilities (facility_percentages) with the body you send. Send every field: one left out is cleared, except supplier_id, file_url, self_consumption, toc, base_total_spend, currency_unit_id and heat_cooling_type, which keep their stored value when left out. To change only some fields, use Update Invoice (PATCH). This is also the route that takes a file_url, to keep the invoice’s PDF with it (Invoices with a PDF).

How it works

The invoice and its split are replaced together. An invoice split across facilities is a group of rows, one per facility. A facility that stays in the split keeps its row and its id; a facility added gets a new row, and one left out is deleted with its emissions.
Swapping one facility for another moves its row in place. When exactly one facility leaves the split and another enters it, the row keeps its id, its comments, its project assignments and its custom-column values, and its emissions are calculated again under the new facility. Any other change of facilities deletes the rows left out and creates new ones, with new ids.
The row can move to another organization: a facility of the invoice’s organization or of an organization below it is accepted. The row’s custom-column values go to that organization’s invoice columns (a column it lacks is created there). The move is refused before anything is written when the invoice would lose data on the way (see Errors).
The emissions are calculated in the request, and the response carries them. A row missing a field its calculation needs ends in status: review, and one with no emission factor to calculate with in status: error; neither carries co2e.

Request

Headers

string

required

Your API key for authentication

string

required

Your organization UUID

Path Parameters

UUID

required

The invoice to replace. For an invoice split across facilities, any of its rows.

Body

string

required

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

number

required

Total consumption of the invoice, before the split.

UUID

required

Unit of base_quantity.

UUID

required

One of the facilities of facility_percentages: the response is its row.

date

required

Start of the invoice period, YYYY-MM-DD.

date

required

End of the invoice period, on or after start_date. A date you change follows the activity dates rule.

array

required

The split across facilities: one entry per facility, with organization_id (the facility’s organization), facility_id and percentage (more than 0 and at most 1, up to 4 decimals). The percentages add up to 1 at most; under 1, the rest of the invoice is not counted.

string

The invoice’s file: a URL Dcycle gave you (for example from the upload of the file), the one the invoice already has, or the file itself as data:<mime type>;base64,<content>, with its name in file_name. Left out, or null, the invoice keeps its file. See Invoices with a PDF.

string

The name of a file_url sent as data:, up to 255 characters (e.g. invoice-2026-09.pdf).

UUID

The invoice’s supplier, as in Create Invoice. Left out, the invoice keeps its supplier; null removes it.

string

The invoice’s number on the bill (not the id in the path).

UUID

A record of your custom emission factor databases to calculate with, instead of the default factor.

string

For water: the supply point (contract).

string

For water: the meter’s number.

number

Total spend of the invoice before the split, in currency_unit_id. It does not change the emissions.

UUID

The fiat-currency unit of base_total_spend, from GET /v2/units.

boolean

For electricity: the electricity comes from your own generation (for example photovoltaic panels).

string

For district_heat_and_steam: heat (district heating, also when it is empty) or cooling (district cooling).

stationary_fuel_id, refrigerant_fuel_id, custom_emission_factor_id, cups and toc mean what they mean in Create Invoice.

Response

200 with the row of facility_id: id, type, status, facility_id, supplier_id, uploaded_by, invoice_id, cups, water_meter_number, water_supply_point, enabled, self_consumption, heat_cooling_type, co2e (that row’s share, in kg CO₂e) and co2e_biomass. To read the other rows, use List Invoices.

Example

curl -X PUT "https://api.dcycle.io/v1/invoices/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "electricity",
    "base_quantity": 3000,
    "unit_id": "c2a5d7e1-4b8f-4e3a-9c6d-1f2e3a4b5c6d",
    "facility_id": "9b2e4c1a-6d3f-4e8b-a7c5-1f0d2e3b4a59",
    "start_date": "2026-09-01",
    "end_date": "2026-09-30",
    "supplier_id": "7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a",
    "cups": "ES0021000000000000AA",
    "facility_percentages": [
      {
        "organization_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "facility_id": "9b2e4c1a-6d3f-4e8b-a7c5-1f0d2e3b4a59",
        "percentage": 1
      }
    ]
  }'

Successful Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "uploaded_by": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "facility_id": "9b2e4c1a-6d3f-4e8b-a7c5-1f0d2e3b4a59",
  "supplier_id": "7d1e2f3a-4b5c-4d6e-8f9a-0b1c2d3e4f5a",
  "status": "active",
  "type": "electricity",
  "invoice_id": "",
  "cups": "ES0021000000000000AA",
  "water_meter_number": null,
  "water_supply_point": null,
  "enabled": true,
  "self_consumption": false,
  "heat_cooling_type": null,
  "co2e": 486.0,
  "co2e_biomass": 0.0
}

Errors

Errors keep the {"code": "...", "detail": "..."} shape of the v1 routes. A body that does not match the schema, or a changed date that breaks the activity dates rule, answers 422 with {"detail": [...]}, one entry per problem.

Status	`code`	When	What to do
`403`	`FACILITY_NOT_IN_ORGANIZATION_GROUP`	A facility of `facility_percentages` is not of the invoice’s organization nor of one below it.	Pick a facility of those organizations.
`403`	`PLAN_FEATURE_NOT_INCLUDED`	Your organization’s plan does not include invoices of that `type`.	Ask an admin of the organization to review its plan with Dcycle.
`404`		The invoice does not exist or is outside your perimeter, or a facility of `facility_percentages` does not exist.	Check the ids. Treat any `404` as not found: check the status, not `code`.
`409`	`INVOICE_MOVE_LINKED_DATA`	The row would move to another organization, but it is assigned to projects of its organization, which cannot follow it.	Remove it from those projects first.
`409`	`INVOICE_MOVE_CUSTOM_SUPPLIER`	The row would move to another organization, but its supplier is a custom one that organization cannot use.	Send a `supplier_id` that organization can use.
`409`	`INVOICE_MOVE_CUSTOM_COLUMN_CONFLICT`	The row would move to another organization, but one of its custom-column values cannot go there: the column has another type there, a list column there does not offer the value, or it is a relation or user column.	Clear those values, or change the column in one of the organizations, first.
`422`	`NEGATIVE_QUANTITY_NOT_ALLOWED`	A negative `base_quantity` on a `type` other than `electricity` or `heat`, or in a currency unit.	Send a quantity of 0 or more, or a credit note in a unit of energy.
`422`	`NET_CONSUMPTION_NEGATIVE`	The replace would take a facility’s consumption of that kind below zero (a credit note larger than its invoices).	Lower the credit note, or add the invoices it corrects first.
`422`	`INVALID_FILE_URL`	`file_url` names a file of an organization you cannot read.	Send a URL of your organization’s files, or the file as `data:`.
`422`	`SUPPLIER_ID_NOT_FOUND`	`supplier_id` does not exist, or your organization cannot use it.	Take the id from the supplier lookup of Create Invoice.
`422`	`INVALID_SUPPLIER_TYPE`	An electricity invoice with a facility in Spain and no `custom_emission_factor_id`, or a `district_heat_and_steam` one, whose supplier (sent, or kept when left out) is of another kind: not electricity, or heat instead of cooling and the other way round.	Send a supplier of the invoice’s kind.
`422`	`CANNOT_PROVIDE_BOTH_SUPPLIER_ID_AND_CUSTOM_EMISSION_FACTOR_ID`	An electricity invoice with a facility in Spain carries both.	Send one of them.
`422`	`INVALID_UNIT`	A `district_heat_and_steam` invoice whose `unit_id` is not kWh, MWh, MJ, GJ or a currency.	Send one of those units.
`422`	`REFRIGERANT_FUEL_NOT_FOUND`	`refrigerant_fuel_id` is not a refrigerant gas.	Send a refrigerant gas id, as in Create Invoice.
`422`	`CUSTOM_EMISSION_FACTOR_NOT_FOUND_OR_DISABLED`, `CUSTOM_EMISSION_FACTOR_HAS_NO_GAS_VALUES`	`custom_emission_factor_id` is not an enabled factor available to the organization of `facility_id` (for a row that moves, to its new organization), or it has no gas values.	Send an enabled factor of that organization.
`422`	`MULTIDB_CUSTOM_RECORD_NOT_FOUND_OR_DISABLED`, `MULTIDB_CUSTOM_RECORD_INCOMPATIBLE_CATEGORY`	`custom_ef_record_id` is not an enabled record of that organization, or it is for another kind of activity.	Send an enabled record of the invoice’s kind.

Update Invoice

Change some fields of an invoice

Invoices with a PDF

Keep the PDF with the invoice

​How it works

​Request

​Headers

​Path Parameters

​Body

​Response

​Example

​Successful Response

​Errors

​Related Endpoints

Update Invoice

Invoices with a PDF

How it works

Request

Headers

Path Parameters

Body

Response

Example

Successful Response

Errors

Related Endpoints