Skip to main content
GET
/
v1
/
purchases
/
totals
Totals
const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/purchases/totals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "total_co2e": 123,
  "total_amount": 123,
  "count": 123,
  "co2e_pct_change": {},
  "amount_pct_change": {}
}

​
Totals

Returns aggregated totals for purchases: total CO2e, total monetary amount (EUR), record count, and percentage change compared to the same period in the previous year. Supports the same filters as the list endpoint.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Query Parameters

​
purchase_date_from
string
Filter purchases on or after this date (ISO format YYYY-MM-DD)
​
purchase_date_to
string
Filter purchases on or before this date (ISO format YYYY-MM-DD)
​
search
string
Search by description or supplier name
​
status[]
string[]
Filter by status. Values: active, error, in_progress, in_review, inactive, pending
​
purchase_type[]
string[]
Filter by calculation methodology. Values: spend_based, supplier_specific
​
expense_type[]
string[]
Filter by expense classification. Values: capex, opex
​
file_id[]
string[]
Filter by file UUID. Use 00000000-0000-0000-0000-000000000000 for manually created records.
​
supplier_id[]
string[]
Filter by supplier UUID
​
unit_id[]
string[]
Filter by currency unit UUID
​
created_at_from
string
Filter records created on or after this date
​
created_at_to
string
Filter records created on or before this date
​
co2e_status
string
Filter by CO2e calculation statusAllowed values: calculated, not_calculated
​
filter_by
string
Per-column filters using the filter grammarExample: quantity:gt100$co2e:bt[10,100]
​
filter_match
string
How to combine filter_by clauses across fieldsAllowed values: any (OR), all (AND, default)
​
filter_or_fields
string
Comma-separated fields whose same-field clauses combine with OR instead of AND

​
Response

​
total_co2e
number
Sum of CO2e (tCO2e) for all matching purchases
​
total_amount
number
Sum of monetary amounts (EUR) for all matching purchases
​
count
integer
Number of matching purchase records
​
co2e_pct_change
number | null
Percentage change in CO2e vs the same period in the previous year. null when no prior-year data exists.
​
amount_pct_change
number | null
Percentage change in monetary amount vs the same period in the previous year. null when no prior-year data exists.

​
Example

curl -X GET "https://api.dcycle.io/v1/purchases/totals?purchase_date_from=2025-01-01&purchase_date_to=2025-12-31" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

​
Successful Response

{
  "total_co2e": 142.75,
  "total_amount": 85230.50,
  "count": 312,
  "co2e_pct_change": -8.3,
  "amount_pct_change": 12.1
}

​
Common Errors

​
401 Unauthorized

Cause: Missing or invalid API key 
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

​
403 Forbidden

Cause: The authenticated user is not a member of the organization 
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

List Purchases

Browse purchases with filters and pagination

Bulk Delete by Filters

Delete all purchases matching filters