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 an API key included in the x-api-key header.

Headers

All requests must include:

string

required

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

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

Field	Type	Description
`id`	UUID	Unique identifier for the purchase
`organization_id`	UUID	Organization the purchase belongs to
`product_name`	string	Name of the product or service (max 255 chars)
`description`	string	Optional description (max 500 chars)
`sector`	string	Economic sector for emission factor lookup
`country`	string	2-letter ISO country code
`quantity`	float	Purchase amount (monetary or physical units)
`unit_id`	string	Unit of measurement (e.g., EUR, USD, kg)
`purchase_date`	date	Date of purchase (YYYY-MM-DD)
`purchase_type`	string	Calculation method: `spend_based` or `supplier_specific`
`expense_type`	string	Classification: `capex` or `opex`
`status`	string	Purchase status (see Status Types)
`recycled`	float	Recycled content percentage (0-1)
`supplier_id`	string	Optional supplier identifier
`custom_emission_factor_id`	UUID	Custom emission factor for supplier-specific
`file_id`	UUID	Linked file/document ID
`file_name`	string	Name of linked file
`file_url`	string	URL to download linked file
`co2e`	float	Calculated CO2 equivalent emissions (kg)
`frequency`	string	Purchase frequency: `once`
`created_at`	datetime	When the purchase was created
`updated_at`	datetime	When the purchase was last updated

Purchase Types

Type	Description	Emission Factor Source
`spend_based`	Calculate emissions based on monetary spend	Sector-specific factors from emission databases
`supplier_specific`	Use supplier-provided emission factors	Custom 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

Type	Description	GHG Protocol Category
`capex`	Capital Expenditure	Scope 3 Category 2 (Capital Goods)
`opex`	Operational Expenditure	Scope 3 Category 1 (Purchased Goods & Services)

Status Types

Status	Description
`active`	Purchase is active and included in calculations
`pending`	Purchase is pending review
`in_progress`	Purchase is being processed
`in_review`	Purchase is under review
`inactive`	Purchase is inactive (excluded from calculations)
`error`	Error 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

Create Purchase: Add purchase with product, quantity, and sector information
Set Type: Choose spend-based or supplier-specific calculation method
Link Supplier Factor (optional): For supplier-specific, link a custom emission factor
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

Status	Meaning	Solution
200	Success	-
201	Created	-
204	No Content (delete successful)	-
400	Bad Request	Check request parameters and format
401	Unauthorized	Verify API key
404	Not Found	Check resource ID or organization
422	Validation Error	Review error details in response
500	Server Error	Contact 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

MCP Tools

Query purchase data from AI assistants via MCP

Recalculate Invoices List Purchases

​Purchases API

​Key Features

​Authentication

​Headers

​Available Endpoints

List Purchases

Get Purchase

Create Purchase

Update Purchase

Delete Purchase

​Data Model

​Purchase Object

​Purchase Attributes

​Purchase Types

​Expense Types

​Status Types

​CO2e Calculation

​Spend-Based Method

​Supplier-Specific Method

​Workflow

​Tracking Purchases

​Bulk Upload

​Error Handling

​Common HTTP Status Codes

​Error Response Format

​Use Cases

​Track Office Supplies Spend

​Calculate Category 1 Totals

​Related Documentation

Scope 3 Category 1 Guide

Custom Emission Factors

Authentication Guide

Suppliers API

MCP Tools

Purchases API

Key Features

Authentication

Headers

Available Endpoints

Data Model

Purchase Object

Purchase Attributes

Purchase Types

Expense Types

Status Types

CO2e Calculation

Spend-Based Method

Supplier-Specific Method

Workflow

Tracking Purchases

Bulk Upload

Error Handling

Common HTTP Status Codes

Error Response Format

Use Cases

Track Office Supplies Spend

Calculate Category 1 Totals

Related Documentation