Consolidate CUPS

Merge duplicate CUPS codes by rewriting invoices to a single target value

POST /v1/invoices/consolidate-cups

cURL

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

200 - Success

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

Show Source object properties

cups · string · required

The source CUPS code to be replaced.

facility_id · UUID · required

The facility the source CUPS belongs to.

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

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

200 - Success

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

Error Codes

Code	HTTP Status	Description
FACILITY_NOT_BELONG_TO_ORGANIZATION	403	A source facility_id is not part of the caller’s organization
CUPS_LOCKED_BY_DATADIS	409	A selected source CUPS is backed by a Datadis supply contract
—	422	target_cups is empty or the request body is malformed