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)

{
  "total_co2e": 123,
  "total_amount": 123,
  "count": 123,
  "co2e_pct_change": {},
  "amount_pct_change": {}
}

GET

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)

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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

string

Filter purchases on or after this date (ISO format YYYY-MM-DD)

string

Filter purchases on or before this date (ISO format YYYY-MM-DD)

string

Search by description or supplier name

string[]

Filter by status. Values: active, error, in_progress, in_review, inactive, pending

string[]

Filter by calculation methodology. Values: spend_based, supplier_specific

string[]

Filter by expense classification. Values: capex, opex

string[]

Filter by file UUID. Use 00000000-0000-0000-0000-000000000000 for manually created records.

string[]

Filter by supplier UUID

string[]

Filter by currency unit UUID

string

Filter records created on or after this date

string

Filter records created on or before this date

string

Filter by CO2e calculation statusAllowed values: calculated, not_calculated

string

Per-column filters using the filter grammarExample: quantity:gt100$co2e:bt[10,100]

string

How to combine filter_by clauses across fieldsAllowed values: any (OR), all (AND, default)

string

Comma-separated fields whose same-field clauses combine with OR instead of AND

Response

number

Sum of CO2e (tCO2e) for all matching purchases

number

Sum of monetary amounts (EUR) for all matching purchases

integer

Number of matching purchase records

number | null

Percentage change in CO2e vs the same period in the previous year. null when no prior-year data exists.

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

​Totals

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​Related Endpoints

List Purchases

Bulk Delete by Filters

Totals

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

Related Endpoints