> ## 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.

# Delete Invoices (v2)

> Delete up to 5,000 invoices of any category by id, asynchronously, as an ingest job

[← Invoices API](/api-reference/invoices/overview)

Delete invoices by id, whatever their category, with their emissions. The request checks every id and answers
`202 Accepted` with a **job**; the invoices are deleted in the background. Follow it with
[`GET /v2/ingest-jobs/{id}`](/api-reference/ingest-jobs/get) or the [`ingest_job.finished`](/api-reference/webhooks/overview) webhook.

<Warning>
  **Permanent.** Deleted invoices and their emissions cannot be recovered. Use `dry_run=true` first if you are not sure.
</Warning>

<Warning>
  **Beta.** Part of the bulk ingest API, currently in beta. The contract may still change before general availability.
</Warning>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/v2/invoices/delete" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Idempotency-Key: 3b2a1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d" \
    -H "Content-Type: application/json" \
    -d '{"ids": ["9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d"]}'
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "2c1d0e9f-8a7b-4c6d-9e5f-4a3b2c1d0e9f",
    "status": "processing",
    "entity_type": "invoices",
    "operation": "delete",
    "source": "api_bulk",
    "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
    "chunks_total": 1,
    "chunks_done": 0,
    "created_at": "2026-10-13T10:52:11.204Z",
    "finished_at": null,
    "links": {
      "self": "/v2/ingest-jobs/2c1d0e9f-8a7b-4c6d-9e5f-4a3b2c1d0e9f",
      "items": "/v2/ingest-jobs/2c1d0e9f-8a7b-4c6d-9e5f-4a3b2c1d0e9f/items"
    }
  }
  ```

  ```json 200 (dry_run=true) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "dry_run": true, "submitted": 1, "valid": 1 }
  ```
</ResponseExample>

## How it works

1. **The request checks every id.** One that does not exist, is outside your organization's perimeter or repeats an
   invoice already in the request rejects the **whole** request with `422`, and nothing is deleted.
2. **An invoice split across facilities goes whole**, whichever of its per-facility invoices the id names.
3. **Invoices imported by Datadis are refused** (`DATADIS_MANAGED`): the next sync would bring them back. Remove the
   supply contract instead.
4. **The job deletes them in the background** with their emissions and calculation data. When every chunk is done the
   job is `completed` (or `completed_with_errors`), and `ingest_job.finished` is sent with `"operation": "delete"`.

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  1 to 255 characters, unique per batch. A retry with the same key and body returns the original job; the same key
  with another body is `422 IDEMPOTENCY_KEY_REUSED`.
</ParamField>

### Query Parameters

<ParamField query="dry_run" type="boolean" default="false">
  Check only: the same `422` for bad ids, nothing deleted, no job.
</ParamField>

### Body Parameters

<ParamField body="ids" type="array[uuid]" required>
  Invoice ids, of any category, 1 to 5,000, each invoice once.
</ParamField>

## Response

`202 Accepted`, the job (`operation: delete`) and a `Location` header to it. One item per invoice, in the order sent.

## Errors

[Problem details](/api-reference/errors). Per-id codes in `errors[].error_code`:

| `error_code` | Cause |
| - | - |
| `NOT_FOUND` | The invoice does not exist, is deleted or is outside your organization's perimeter (all answer the same). |
| `DUPLICATE_ID` | The invoice is already in the request (the same id, or another of its per-facility invoices). |
| `DATADIS_MANAGED` | The invoice was imported by Datadis. |

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Electricity Invoices (v2)" icon="bolt" href="/api-reference/invoices/electricity-create-v2">
    Create up to 5,000 electricity invoices
  </Card>

  <Card title="Get Ingest Job" icon="magnifying-glass" href="/api-reference/ingest-jobs/get">
    Follow the deletion
  </Card>
</CardGroup>


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