Custom Emission Factors - Dcycle Platform Docs

Early Access - The Dcycle CLI is currently available for enterprise customers. Contact us to learn more about access.

Overview

Upload organization-specific emission factors to override standard database values. Custom factors improve accuracy when you have supplier-provided data. Factors are grouped by category and support both simple (CO2e only) and advanced (CO2 + CH4 + N2O) tags.

Available Commands

Command	Description
`dcy custom-ef upload [file.csv]`	Upload custom emission factors from CSV
`dcy custom-ef delete-bulk <file>`	Bulk delete custom emission groups from a file

Generate Template

Download a CSV template with the required column format:

dcy custom-ef upload --template

Output:

template generated: custom_ef_template.csv

The template includes all supported columns with example data rows covering electricity, heat, and waste categories.

Required Columns

Column	Description
`group_name`	Name of the emission factor group
`group_category`	Category: `heat`, `recharge`, `process`, `water`, `electricity`, `vehicles`, `waste`, `purchases`
`group_ghg_type`	GHG type: `0` or `1`
`ef_name`	Name of the individual emission factor
`unit_id`	Unit UUID (use `dcy units list` to find IDs)
`tag`	`simple` (CO2e value only) or `advanced` (CO2 + CH4 + N2O)
`factor_start_date`	Start date (YYYY-MM-DD)
`factor_end_date`	End date (YYYY-MM-DD)

Optional Columns

Column	Applies to	Description
`group_description`	All	Group description text
`uncertainty_grade`	All	0–100 uncertainty rating
`value_co2e`	`tag=simple`	CO2e emission factor value
`value_co2`	`tag=advanced`	CO2 emission factor value
`value_ch4`	`tag=advanced`	CH4 emission factor value
`value_n2o`	`tag=advanced`	N2O emission factor value
`renewable_percentage`	Energy categories	0–1 renewable fraction
`hazardous`	`waste`	`true`/`false`
`recycled`	`waste`	`true`/`false`
`low_code`	`waste`	LoW (List of Waste) code
`rd_code`	`waste`	R/D disposal code

Validate Before Uploading

Run a dry-run to check your CSV for errors without actually uploading:

dcy custom-ef upload factors.csv --dry-run

Output:

Dry-run mode: no API calls were made
File: factors.csv
Groups to create: 2
Factors to create: 4

If validation errors are found, the command prints row-by-row errors and exits without uploading.

Upload Emission Factors

dcy custom-ef upload factors.csv

Output:

File: factors.csv
Groups to create: 2
Factors to create: 4
group created: Grid Spain 2023 (abc123-...)
  factor created: Jan-Jun 2023
  factor created: Jul-Dec 2023
group created: Custom Gas (def456-...)
  factor created: Natural Gas 2023
Groups created: 2
Groups failed: 0
Factors created: 3
Factors failed: 0

Flags

Flag	Short	Default	Description
`--template`	`-t`	`false`	Generate a blank CSV template instead of uploading
`--dry-run`	—	`false`	Validate and summarize without making API calls
`--skip-validation`	—	`false`	Skip local CSV validation (rely on server-side checks)
`--org`	—	—	Organization ID override

Examples

# Generate template
dcy custom-ef upload --template

# Validate without uploading
dcy custom-ef upload factors.csv --dry-run

# Upload with JSON output
dcy custom-ef upload factors.csv --format json

# Skip local validation
dcy custom-ef upload factors.csv --skip-validation

Bulk Delete Groups

Delete multiple custom emission groups by providing a text file with one ID per line:

dcy custom-ef delete-bulk ids.txt --yes

Output:

deleted: 3

If some deletions fail:

2 failed: group not found
deleted: 1
failed: 2

Flags

Flag	Short	Default	Description
`--yes`	`-y`	`false`	Skip confirmation prompt
`--org`	—	—	Organization ID override

The file should contain one custom emission group UUID per line. Blank lines and duplicates are automatically skipped.

Typical Workflows

Upload Custom Emission Factors

# 1. Get the template
dcy custom-ef upload --template

# 2. Fill in your data (edit custom_ef_template.csv)

# 3. Validate
dcy custom-ef upload custom_ef_template.csv --dry-run

# 4. Upload
dcy custom-ef upload custom_ef_template.csv

Replace Emission Factors

# 1. Delete old groups
dcy custom-ef delete-bulk old-group-ids.txt --yes

# 2. Upload new CSV
dcy custom-ef upload updated_factors.csv

Find Unit IDs for Your Factors

# Find the unit ID for kWh
dcy units list --search kWh --format json | jq -r '.[0].id'

Next Steps

Units

Find unit IDs for emission factor definitions

LCA Materials

Link materials to ecoinvent activities

Invoices

Manage energy invoices using your custom factors

Data Imports

Bulk import CSV/Excel data with guided mapping

​Overview

​Available Commands

​Generate Template

​Required Columns

​Optional Columns

​Validate Before Uploading

​Upload Emission Factors

​Flags

​Examples

​Bulk Delete Groups

​Flags

​Typical Workflows

​Upload Custom Emission Factors

​Replace Emission Factors

​Find Unit IDs for Your Factors

​Next Steps

Units

LCA Materials

Invoices

Data Imports

Overview

Available Commands

Generate Template

Required Columns

Optional Columns

Validate Before Uploading

Upload Emission Factors

Flags

Examples

Bulk Delete Groups

Flags

Typical Workflows

Upload Custom Emission Factors

Replace Emission Factors

Find Unit IDs for Your Factors

Next Steps