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));
import requests

url = "https://api.dcycle.io/v1/purchases/totals"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)
curl --request GET \
  --url https://api.dcycle.io/v1/purchases/totals \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'
{
  "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 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}"
import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
}

response = requests.get(
    "https://api.dcycle.io/v1/purchases/totals",
    headers=headers,
    params={
        "purchase_date_from": "2025-01-01",
        "purchase_date_to": "2025-12-31",
    },
)

totals = response.json()
print(f"CO2e: {totals['total_co2e']:.2f} tCO2e ({totals['co2e_pct_change']:+.1f}% YoY)")
print(f"Amount: €{totals['total_amount']:,.2f} | {totals['count']} purchases")
const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
};

axios.get('https://api.dcycle.io/v1/purchases/totals', {
  headers,
  params: {
    purchase_date_from: '2025-01-01',
    purchase_date_to: '2025-12-31',
  },
})
.then(response => {
  const { total_co2e, total_amount, count, co2e_pct_change } = response.data;
  console.log(`CO2e: ${total_co2e.toFixed(2)} tCO2e (${co2e_pct_change > 0 ? '+' : ''}${co2e_pct_change}% YoY)`);
  console.log(`Amount: €${total_amount.toLocaleString()} | ${count} purchases`);
});

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