Delete Invoices (v2)

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

POST /v2/invoices/delete

cURL

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

202

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

← Invoices API

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} or the ingest_job.finished webhook.

Permanent. Deleted invoices and their emissions cannot be recovered. Use dry_run=true first if you are not sure.

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

cURL

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

202

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

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

x-api-key · string · required

Your API key for authentication

x-organization-id · string · required

Your organization UUID

Idempotency-Key · 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.

Query Parameters

dry_run · boolean · default: "false"

Check only: the same 422 for bad ids, nothing deleted, no job.

Body Parameters

ids · array[uuid] · required

Invoice ids, of any category, 1 to 5,000, each invoice once.

Response

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

Errors

Problem details. 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

Create Electricity Invoices (v2)

Create up to 5,000 electricity invoices

Get Ingest Job

Follow the deletion