> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Emission Factors

> Create and manage custom emission factors for your organization

<Warning>
  **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.
</Warning>

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.

<Warning>
  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.
</Warning>

## 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

<Steps>
  <Step title="Create Custom Emission Group">
    First, create a group (category) to organize your custom factors

    ```
    POST /api/v1/custom_emission_groups
    ```
  </Step>

  <Step title="Add Custom Emission Factors">
    Add individual emission factors to the group

    ```
    POST /api/v1/custom_emission_factors/{group_id}
    ```
  </Step>

  <Step title="Use in Purchases/Wastes">
    Reference your custom factor when creating purchases or wastes

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "custom_emission_factor_id": "your-factor-uuid",
      ...
    }
    ```
  </Step>

  <Step title="Monitor & Update">
    Review and update factors annually or when supplier data changes

    ```
    PATCH /api/v1/custom_emission_factors/{id}
    ```
  </Step>
</Steps>

## Data Structure

### Custom Emission Group

A group organizes related custom emission factors:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 |

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

## Categories

Custom emission factors are organized by category:

### Purchases (`purchases`)

* Supplier-specific product emission factors
* Custom service emission calculations
* Industry-specific materials

**Example:** Recycled steel from certified supplier with EPD documentation

### Wastes (`wastes`)

* Custom waste treatment emission factors
* Specific disposal method emissions
* Regional waste processing differences

**Example:** Incineration with energy recovery at specific facility

### Energy (`energy`)

* Renewable energy contracts with specific grid mix
* Power Purchase Agreements (PPAs)
* On-site generation (solar, wind)

**Example:** 100% renewable energy from wind farm PPA

## 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 |

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

## Best Practices

### 1. Document Everything

Always document the source and methodology:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"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

<CardGroup cols={2}>
  <Card title="Create Factor" icon="plus" href="/api-docs/custom-emission-factors/create">
    Add new custom emission factor
  </Card>

  <Card title="List Factors" icon="list" href="/api-docs/custom-emission-factors/list">
    View factors in a group
  </Card>

  <Card title="Get Factor" icon="magnifying-glass" href="/api-docs/custom-emission-factors/get">
    Retrieve specific factor details
  </Card>

  <Card title="Update Factor" icon="pen" href="/api-docs/custom-emission-factors/update">
    Modify existing factor
  </Card>

  <Card title="Delete Factor" icon="trash" href="/api-docs/custom-emission-factors/delete">
    Remove custom factor
  </Card>

  <Card title="Manage Groups" icon="folder" href="/api-docs/custom-emission-groups/overview">
    Create and organize groups
  </Card>
</CardGroup>

## Common Use Cases

### Supplier-Specific Product Factors

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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
}
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Custom Emission Groups" icon="folder-tree" href="/api-docs/custom-emission-groups/overview">
    Organize custom factors into groups
  </Card>

  <Card title="Purchases" icon="shopping-cart" href="/api-docs/purchases/list">
    Use custom factors in purchases
  </Card>

  <Card title="Wastes" icon="trash" href="/api-docs/wastes/codes">
    Apply to waste management
  </Card>

  <Card title="Units" icon="ruler" href="/api-reference/legacy/units/list">
    Available measurement units
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.