Skip to main content
GET
/
v1
/
invoices
/
cups
curl -X GET "https://api.dcycle.io/v1/invoices/cups?facility_id=da59c96f-995a-4ec3-88bd-465dcbabf63d&page=1&size=50" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "x-api-key: YOUR_API_KEY"

{
  "items": [
    {
      "cups": "ES0021000000000000001AB",
      "facility_id": "da59c96f-995a-4ec3-88bd-465dcbabf63d",
      "facility_name": "Facility 1",
      "invoice_count": 45,
      "first_date": "2024-01-01",
      "last_date": "2024-12-31",
      "is_locked": false
    }
  ],
  "total": 11,
  "page": 1,
  "size": 50,
  "total_pages": 1
}

​
Overview

Returns a paginated list of distinct CUPS groups for your organization. Each group represents a unique combination of (cups, facility) over the organization’s electricity invoices, together with aggregate metadata such as the number of invoices and the date range they span. This is the data behind the “Consolidate CUPS” workflow: it lets you spot duplicate or near-duplicate CUPS codes that should be merged into a single canonical value (see Consolidate CUPS).
A group is reported as locked (is_locked: true) when any invoice in it is backed by a Datadis supply contract. Locked groups cannot be consolidated.

​
Query Parameters

​
facility_id
UUID
Restrict the result to CUPS groups belonging to a single facility.Example: ?facility_id=da59c96f-995a-4ec3-88bd-465dcbabf63d
​
search
string
Case-insensitive substring match against the CUPS code.Example: ?search=000001AB
​
page
integer
default:"1"
Page number for pagination. Must be ≥ 1.
​
size
integer
default:"50"
Number of items per page. Must be between 1 and 200.

​
Response

​
items
array
List of CUPS group objects.
​
total
integer
Total number of CUPS groups matching the filters.
​
page
integer
Current page number.
​
size
integer
Number of items per page.
​
total_pages
integer
Total number of pages.
curl -X GET "https://api.dcycle.io/v1/invoices/cups?facility_id=da59c96f-995a-4ec3-88bd-465dcbabf63d&page=1&size=50" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -H "x-api-key: YOUR_API_KEY"

{
  "items": [
    {
      "cups": "ES0021000000000000001AB",
      "facility_id": "da59c96f-995a-4ec3-88bd-465dcbabf63d",
      "facility_name": "Facility 1",
      "invoice_count": 45,
      "first_date": "2024-01-01",
      "last_date": "2024-12-31",
      "is_locked": false
    }
  ],
  "total": 11,
  "page": 1,
  "size": 50,
  "total_pages": 1
}