Custom Emission Factors - Dcycle Platform Docs

Legacy API. This page documents the previous version of the API. This particular operation has no documented equivalent in the current API yet, so this remains the documented way to do it. Prefer the current API for everything it already covers.

Custom emission factors allow you to define organization-specific emission factors when Dcycle’s standard factors don’t match your exact needs. This is an advanced feature for users with detailed LCA (Life Cycle Assessment) data from suppliers or custom calculations.

Custom emission factors should only be used when you have verified, supplier-specific emission data. Using incorrect factors can significantly impact the accuracy of your carbon footprint calculations.

Overview

What are Custom Emission Factors?

Custom emission factors are user-defined emission values that override Dcycle’s standard database factors for specific products, services, or processes. They are organized into Custom Emission Groups (categories) and can be applied to:

Purchases - Supplier-specific product emission factors
Wastes - Custom waste treatment emission factors
Energy - Renewable energy with specific grid mix data

When to Use Custom Factors

✅ Use custom factors when:

You have supplier-provided LCA data with verified emission factors
Your product/service has unique characteristics not captured by standard factors
You need to track specific renewable energy contracts (PPAs)
Regulatory requirements demand specific calculation methodologies

❌ Don’t use custom factors when:

Standard Dcycle factors are available and appropriate
You’re guessing or estimating without verified data
You want to artificially lower your emissions (greenwashing)

Workflow

Create Custom Emission Group

First, create a group (category) to organize your custom factors

POST /api/v1/custom_emission_groups

Add Custom Emission Factors

Add individual emission factors to the group

POST /api/v1/custom_emission_factors/{group_id}

Use in Purchases/Wastes

Reference your custom factor when creating purchases or wastes

{
  "custom_emission_factor_id": "your-factor-uuid",
  ...
}

Monitor & Update

Review and update factors annually or when supplier data changes

PATCH /api/v1/custom_emission_factors/{id}

Data Structure

Custom Emission Group

A group organizes related custom emission factors:

{
  "id": "group-uuid",
  "name": "Supplier XYZ Products",
  "description": "LCA data from Supplier XYZ 2024",
  "category": "purchases",  // or "wastes", "energy"
  "ghg_type": 1,  // 1=fossil, 2=biogenic, 3=mixed
  "organization_id": "your-org-uuid"
}

Custom Emission Factor

An individual factor within a group:

{
  "id": "factor-uuid",
  "ef_name": "Recycled Aluminum Sheets",
  "unit_id": "kg-unit-uuid",
  "factor_uploaded_by": "procurement_team",
  "tag": "advanced",  // "simple" or "advanced"
  "uncertainty_grade": 15.5,  // 0-100 percentage
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31",
  "emission_factor_values": [
    {
      "gas_type": "CO2",
      "value": 2.15  // kg CO2 per kg aluminum
    },
    {
      "gas_type": "CH4",
      "value": 0.008  // kg CH4 per kg aluminum
    },
    {
      "gas_type": "N2O",
      "value": 0.002  // kg N2O per kg aluminum
    }
  ],
  "recycled": true,  // For waste factors
  "renewable_percentage": null  // For energy factors
}

Gas Types

Custom factors can include multiple greenhouse gases:

Gas Type	Description	GWP (100-year)
`CO2`	Carbon Dioxide	1
`CH4`	Methane	28
`N2O`	Nitrous Oxide	265
`HFC`	Hydrofluorocarbons	Varies
`PFC`	Perfluorocarbons	Varies
`SF6`	Sulfur Hexafluoride	23,500
`NF3`	Nitrogen Trifluoride	16,100

Dcycle automatically converts all gases to CO2 equivalent (CO2e) using IPCC AR6 Global Warming Potential values.

Uncertainty Grades

Track the confidence level of your custom factors:

Grade	Description	When to Use
0-20%	High confidence	Supplier-verified LCA, EPD, audited data
21-40%	Medium confidence	Industry averages, peer-reviewed studies
41-60%	Moderate confidence	Estimated with reasonable assumptions
61-80%	Low confidence	Limited data, significant assumptions
81-100%	Very low confidence	Rough estimates, should be improved

Document the source of your emission factors in the additional_docs field and aim to reduce uncertainty over time by obtaining better data.

Best Practices

1. Document Everything

Always document the source and methodology:

{
  "ef_name": "Recycled Plastic Granules - Supplier ABC",
  "additional_docs": "Based on EPD from ABC Plastics, dated 2024-01-15. Verified by third-party auditor. Includes recycling process emissions.",
  "factor_uploaded_by": "sustainability_team@company.com",
  "uncertainty_grade": 15
}

2. Set Validity Periods

Update factors regularly:

{
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31"  // Review annually
}

3. Include All GHGs

Don’t just use CO2 - include CH4, N2O when available:

"emission_factor_values": [
  {"gas_type": "CO2", "value": 2.15},
  {"gas_type": "CH4", "value": 0.008},  // Often significant
  {"gas_type": "N2O", "value": 0.002}   // High GWP impact
]

4. Use Appropriate Units

Match units to your usage:

Mass-based: kg, ton (for solid materials)
Volume-based: L, m³ (for liquids, gases)
Energy-based: kWh, MJ (for energy products)
Currency-based: EUR, USD (as last resort)

5. Tag Complexity Appropriately

Simple tag: Basic single-value factors
Advanced tag: Multi-gas, time-variant, or complex calculations

Validation Requirements

Dcycle validates custom factors to ensure data quality:

Required Fields

✅ Emission factor name (ef_name)
✅ Unit ID (unit_id)
✅ At least one emission value (CO2 minimum)
✅ Uploaded by reference (factor_uploaded_by)
✅ Tag (simple or advanced)

Optional but Recommended

📝 Uncertainty grade (0-100%)
📝 Validity period (start/end dates)
📝 Documentation reference (additional_docs)
📝 Additional gases (CH4, N2O)

Automatic Checks

⚠️ Values must be non-negative
⚠️ Uncertainty grade must be 0-100%
⚠️ End date must be after start date
⚠️ Gas types must be valid (CO2, CH4, N2O, etc.)

API Endpoints

Create Factor

Add new custom emission factor

List Factors

View factors in a group

Get Factor

Retrieve specific factor details

Update Factor

Modify existing factor

Delete Factor

Remove custom factor

Manage Groups

Create and organize groups

Common Use Cases

Supplier-Specific Product Factors

When a supplier provides EPD (Environmental Product Declaration) data:

{
  "ef_name": "Supplier ABC - Recycled Aluminum Sheet",
  "unit_id": "kg-unit-uuid",
  "factor_uploaded_by": "procurement@company.com",
  "tag": "advanced",
  "uncertainty_grade": 12,
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31",
  "additional_docs": "EPD No. ABC-2024-001, Third-party verified",
  "emission_factor_values": [
    {"gas_type": "CO2", "value": 2.15},
    {"gas_type": "CH4", "value": 0.008}
  ],
  "recycled": true
}

Renewable Energy PPA

For Power Purchase Agreements with specific renewable sources:

{
  "ef_name": "Wind Farm PPA - Northern Region",
  "unit_id": "kwh-unit-uuid",
  "factor_uploaded_by": "energy_manager@company.com",
  "tag": "advanced",
  "uncertainty_grade": 5,
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2034-12-31",  // 10-year PPA
  "additional_docs": "PPA Contract #2024-WIND-001",
  "emission_factor_values": [
    {"gas_type": "CO2", "value": 0.0}  // Zero direct emissions
  ],
  "renewable_percentage": 100.0
}

Custom Waste Treatment

For facility-specific waste treatment emissions:

{
  "ef_name": "Local Incinerator with Energy Recovery",
  "unit_id": "kg-unit-uuid",
  "factor_uploaded_by": "waste_manager@company.com",
  "tag": "advanced",
  "uncertainty_grade": 25,
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31",
  "additional_docs": "Facility report Q4 2023, includes energy credit",
  "emission_factor_values": [
    {"gas_type": "CO2", "value": 0.45},  // Net after energy recovery
    {"gas_type": "CH4", "value": 0.002},
    {"gas_type": "N2O", "value": 0.015}  // Higher from incineration
  ],
  "hazardous": false,
  "low_code": "19 12 10",  // Combustible waste
  "rd_code": "R1"  // Energy recovery
}

Custom Emission Groups

Organize custom factors into groups

Purchases

Use custom factors in purchases

Wastes

Apply to waste management

Units

Available measurement units

​Overview

​What are Custom Emission Factors?

​When to Use Custom Factors

​Workflow

​Data Structure

​Custom Emission Group

​Custom Emission Factor

​Gas Types

​Categories

​Purchases (purchases)

​Wastes (wastes)

​Energy (energy)

​Uncertainty Grades

​Best Practices

​1. Document Everything

​2. Set Validity Periods

​3. Include All GHGs

​4. Use Appropriate Units

​5. Tag Complexity Appropriately

​Validation Requirements

​Required Fields

​Optional but Recommended

​Automatic Checks

​API Endpoints

Create Factor

List Factors

Get Factor

Update Factor

Delete Factor

Manage Groups

​Common Use Cases

​Supplier-Specific Product Factors

​Renewable Energy PPA

​Custom Waste Treatment

​Related Documentation

Custom Emission Groups

Purchases

Wastes

Units

Overview

What are Custom Emission Factors?

When to Use Custom Factors

Workflow

Data Structure

Custom Emission Group

Custom Emission Factor

Gas Types

Categories

Purchases (`purchases`)

Wastes (`wastes`)

Energy (`energy`)

Uncertainty Grades

Best Practices

1. Document Everything

2. Set Validity Periods

3. Include All GHGs

4. Use Appropriate Units

5. Tag Complexity Appropriately

Validation Requirements

Required Fields

Optional but Recommended

Automatic Checks

API Endpoints

Common Use Cases

Supplier-Specific Product Factors

Renewable Energy PPA

Custom Waste Treatment

Related Documentation