> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace Invoice

> Replace an invoice and its facility split, attach its PDF, or move it to another organization's facility

[← Invoices API](https://code.dcycle.io/api-reference/invoices/overview.md)

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](https://code.dcycle.io/api-reference/invoices/update.md) (`PATCH`). This is also the route that takes a `file_url`, to
keep the invoice's PDF with it ([Invoices with a PDF](https://code.dcycle.io/api-reference/invoices/invoice-with-pdf.md)).

## How it works

1. **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.
2. **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.
3. **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](#errors)).
4. **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

**x-api-key** `string` *required*

Your API key for authentication

**x-organization-id** `string` *required*

Your organization UUID

### Path Parameters

**invoice\_id** `UUID` *required*

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

### Body

**type** `string` *required*

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

**base\_quantity** `number` *required*

Total consumption of the invoice, before the split.

**unit\_id** `UUID` *required*

Unit of `base_quantity`.

**facility\_id** `UUID` *required*

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

**start\_date** `date` *required*

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

**end\_date** `date` *required*

End of the invoice period, on or after `start_date`. A date you change follows the
[activity dates rule](https://code.dcycle.io/api-reference/ingest-jobs/overview.md#activity-dates).

**facility\_percentages** `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.

**file\_url** `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](https://code.dcycle.io/api-reference/invoices/invoice-with-pdf.md).

**file\_name** `string`

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

**supplier\_id** `UUID`

The invoice's supplier, as in [Create Invoice](https://code.dcycle.io/api-reference/invoices/create.md). Left out, the invoice keeps its
supplier; `null` removes it.

**invoice\_id** `string`

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

**custom\_ef\_record\_id** `UUID`

A record of your [custom emission factor databases](https://code.dcycle.io/api-reference/custom-emission-factors/overview.md) to calculate
with, instead of the default factor.

**water\_supply\_point** `string`

For `water`: the supply point (contract).

**water\_meter\_number** `string`

For `water`: the meter's number.

**base\_total\_spend** `number`

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

**currency\_unit\_id** `UUID`

The fiat-currency unit of `base_total_spend`, from [`GET /v2/units`](https://code.dcycle.io/api-reference/units/list).

**self\_consumption** `boolean`

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

**heat\_cooling\_type** `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](https://code.dcycle.io/api-reference/invoices/create.md).

## 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](https://code.dcycle.io/api-reference/invoices/list.md).

## Example

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](https://code.dcycle.io/api-reference/ingest-jobs/overview.md#activity-dates), 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](https://code.dcycle.io/api-reference/invoices/create.md). |
| `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](https://code.dcycle.io/api-reference/invoices/create.md). |
| `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. |

## Related Endpoints

> [card] [Update Invoice](https://code.dcycle.io/api-reference/invoices/update.md)
>
> Change some fields of an invoice

> [card] [Invoices with a PDF](https://code.dcycle.io/api-reference/invoices/invoice-with-pdf.md)
>
> Keep the PDF with the invoice


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.