Skip to main content
POST
/
v1
/
invoices
/
consolidate-cups
curl -X POST "https://api.dcycle.io/v1/invoices/consolidate-cups" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_cups": "ES0021000000000000001AB",
    "sources": [
      { "cups": "ES0021000000000000001A", "facility_id": "da59c96f-995a-4ec3-88bd-465dcbabf63d" },
      { "cups": "ES0021000000000000001",  "facility_id": "da59c96f-995a-4ec3-88bd-465dcbabf63d" }
    ]
  }'

{
  "updated_count": 35,
  "affected_facilities": ["da59c96f-995a-4ec3-88bd-465dcbabf63d"]
}

​
Consolidate CUPS

Consolidates duplicate or near-duplicate CUPS codes by rewriting the cups field on the matching electricity invoices to a single canonical target_cups value. Use List CUPS Groups first to discover the groups that should be merged. Only electricity invoices that match one of the provided source (cups, facility_id) pairs and that are not backed by a Datadis supply contract are rewritten.
Consolidation only changes the cups value on the matched invoices. It does not reassign facilities and does not recalculate emissions. If you need to recalculate after consolidating, use Recalculate Invoices.

​
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: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

​
Body Parameters

​
target_cups
string
required
The canonical CUPS value to write onto every matched invoice. Must be non-empty.Example: ES0021000000000000001AB
​
sources
array
required
The (cups, facility_id) pairs whose invoices should be rewritten to target_cups.

​
Response

{
  "updated_count": 35,
  "affected_facilities": ["da59c96f-995a-4ec3-88bd-465dcbabf63d"]
}
​
updated_count
integer
Number of invoices whose cups was rewritten.
​
affected_facilities
array of UUID
Facilities that had at least one invoice rewritten.
curl -X POST "https://api.dcycle.io/v1/invoices/consolidate-cups" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_cups": "ES0021000000000000001AB",
    "sources": [
      { "cups": "ES0021000000000000001A", "facility_id": "da59c96f-995a-4ec3-88bd-465dcbabf63d" },
      { "cups": "ES0021000000000000001",  "facility_id": "da59c96f-995a-4ec3-88bd-465dcbabf63d" }
    ]
  }'

{
  "updated_count": 35,
  "affected_facilities": ["da59c96f-995a-4ec3-88bd-465dcbabf63d"]
}

​
Error Codes

CodeHTTP StatusDescription
FACILITY_NOT_BELONG_TO_ORGANIZATION403A source facility_id is not part of the caller’s organization
CUPS_LOCKED_BY_DATADIS409A selected source CUPS is backed by a Datadis supply contract
—422target_cups is empty or the request body is malformed