Skip to main content

​
Purchases API

The Purchases API allows you to create, retrieve, update, and delete purchase records for tracking Scope 3 Category 1 (Purchased Goods and Services) emissions. Purchases can be tracked using spend-based or supplier-specific methodologies for accurate CO2e calculations.
GHG Protocol Scope 3 Category 1Purchased Goods and Services covers emissions from the production of goods and services purchased by your organization. This API helps you collect and manage the data needed for accurate Category 1 reporting using either spend-based or supplier-specific emission factors.

​
Key Features

  • Purchase Management: Create and manage purchase records with supplier and product information
  • Spend-Based Tracking: Calculate emissions based on monetary spend and sector-specific emission factors
  • Supplier-Specific Factors: Use custom emission factors for more accurate calculations
  • CAPEX/OPEX Classification: Distinguish between capital and operational expenditures
  • File Attachments: Link purchases to uploaded documents (invoices, receipts)
  • Pagination Support: Efficiently retrieve large purchase lists
  • Filtering: Filter purchases by status, type, expense type, and file

​
Authentication

All endpoints require authentication using either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

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

​
Available Endpoints

List Purchases

Retrieve all purchases with filtering and pagination

Get Purchase

Get a specific purchase by ID

Create Purchase

Add a new purchase to your organization

Update Purchase

Modify purchase details

Delete Purchase

Remove a purchase from your organization

​
Data Model

​
Purchase Object

The purchase object contains detailed information about a purchased good or service: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "product_name": "Office Supplies",
  "description": "Q1 2024 office supplies order",
  "sector": "Manufacturing",
  "country": "ES",
  "quantity": 1500.00,
  "unit_id": "EUR",
  "purchase_date": "2024-03-15",
  "purchase_type": "spend_based",
  "expense_type": "opex",
  "status": "active",
  "recycled": 0.25,
  "supplier_id": "supplier-123",
  "custom_emission_factor_id": null,
  "file_id": "660e8400-e29b-41d4-a716-446655440000",
  "file_name": "invoice_q1_2024.pdf",
  "file_url": "https://storage.dcycle.io/...",
  "co2e": 245.5,
  "frequency": "once",
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}

​
Purchase Attributes

FieldTypeDescription
idUUIDUnique identifier for the purchase
organization_idUUIDOrganization the purchase belongs to
product_namestringName of the product or service (max 255 chars)
descriptionstringOptional description (max 500 chars)
sectorstringEconomic sector for emission factor lookup
countrystring2-letter ISO country code
quantityfloatPurchase amount (monetary or physical units)
unit_idstringUnit of measurement (e.g., EUR, USD, kg)
purchase_datedateDate of purchase (YYYY-MM-DD)
purchase_typestringCalculation method: spend_based or supplier_specific
expense_typestringClassification: capex or opex
statusstringPurchase status (see Status Types)
recycledfloatRecycled content percentage (0-1)
supplier_idstringOptional supplier identifier
custom_emission_factor_idUUIDCustom emission factor for supplier-specific
file_idUUIDLinked file/document ID
file_namestringName of linked file
file_urlstringURL to download linked file
co2efloatCalculated CO2 equivalent emissions (kg)
frequencystringPurchase frequency: once
created_atdatetimeWhen the purchase was created
updated_atdatetimeWhen the purchase was last updated

​
Purchase Types

TypeDescriptionEmission Factor Source
spend_basedCalculate emissions based on monetary spendSector-specific factors from emission databases
supplier_specificUse supplier-provided emission factorsCustom emission factor linked via custom_emission_factor_id
Spend-Based vs Supplier-Specific
  • Spend-based is easier to implement but less accurate. It uses average emission factors for economic sectors.
  • Supplier-specific requires more data but provides more accurate results by using actual emission factors from your suppliers.

​
Expense Types

TypeDescriptionGHG Protocol Category
capexCapital ExpenditureScope 3 Category 2 (Capital Goods)
opexOperational ExpenditureScope 3 Category 1 (Purchased Goods & Services)

​
Status Types

StatusDescription
activePurchase is active and included in calculations
pendingPurchase is pending review
in_progressPurchase is being processed
in_reviewPurchase is under review
inactivePurchase is inactive (excluded from calculations)
errorError occurred during processing

​
CO2e Calculation

Emissions are calculated using different methodologies based on purchase type:

​
Spend-Based Method

CO2e = Spend Amount (EUR) x Sector Emission Factor (kg CO2e/EUR) x (1 - Recycled %)

​
Supplier-Specific Method

CO2e = Quantity x Custom Emission Factor (from supplier)

​
Workflow

​
Tracking Purchases

  1. Create Purchase: Add purchase with product, quantity, and sector information
  2. Set Type: Choose spend-based or supplier-specific calculation method
  3. Link Supplier Factor (optional): For supplier-specific, link a custom emission factor
  4. Query Results: Retrieve purchases to see calculated CO2e

​
Bulk Upload

For large volumes of purchases, use the CSV bulk upload feature in the Dcycle app or the Legacy API bulk upload endpoint.

​
Error Handling

​
Common HTTP Status Codes

StatusMeaningSolution
200Success-
201Created-
204No Content (delete successful)-
400Bad RequestCheck request parameters and format
401UnauthorizedVerify API key
404Not FoundCheck resource ID or organization
422Validation ErrorReview error details in response
500Server ErrorContact support if persists

​
Error Response Format

{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

​
Use Cases

​
Track Office Supplies Spend

Monitor CO2e emissions for office supply purchases: 
import requests

# Create purchase
purchase = requests.post(
    "https://api.dcycle.io/v1/purchases",
    headers=headers,
    json={
        "product_name": "Office Supplies Q1",
        "sector": "Manufacturing",
        "country": "ES",
        "quantity": 2500.00,
        "unit_id": "EUR",
        "purchase_date": "2024-03-15",
        "purchase_type": "spend_based",
        "expense_type": "opex",
        "recycled": 0.3
    }
).json()

print(f"CO2e: {purchase['co2e']} kg")

​
Calculate Category 1 Totals

Sum up all purchased goods and services emissions: 
# Get all active purchases
response = requests.get(
    "https://api.dcycle.io/v1/purchases",
    headers=headers,
    params={"status[]": ["active"], "size": 100}
).json()

total_co2e = sum(p.get("co2e", 0) for p in response["items"])
print(f"Scope 3 Category 1 Total: {total_co2e} kg CO2e ({total_co2e/1000:.1f} tonnes)")

Scope 3 Category 1 Guide

Complete tutorial for tracking Scope 3 Category 1 emissions

Custom Emission Factors

Create supplier-specific emission factors

Authentication Guide

Learn how to authenticate API requests

Suppliers API

Manage supplier data