Update Custom Emission Factor

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'x-user-id': '<x-user-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    factor_uploaded_by: '<string>',
    ef_name: '<string>',
    emission_factor_values: [{}],
    additional_docs: '<string>',
    low_code: '<string>',
    rd_code: '<string>',
    hazardous: true,
    recycled: true
  })
};

fetch('https://api.dcycle.io/api/v1/custom_emission_factors/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/api/v1/custom_emission_factors/{id}"

payload = {
    "factor_uploaded_by": "<string>",
    "ef_name": "<string>",
    "emission_factor_values": [{}],
    "additional_docs": "<string>",
    "low_code": "<string>",
    "rd_code": "<string>",
    "hazardous": True,
    "recycled": True
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "x-user-id": "<x-user-id>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/api/v1/custom_emission_factors/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "factor_uploaded_by": "<string>",
  "ef_name": "<string>",
  "emission_factor_values": [
    {}
  ],
  "additional_docs": "<string>",
  "low_code": "<string>",
  "rd_code": "<string>",
  "hazardous": true,
  "recycled": true
}
'

PATCH

api

custom_emission_factors

{id}

Update Custom Emission Factor

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'x-user-id': '<x-user-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    factor_uploaded_by: '<string>',
    ef_name: '<string>',
    emission_factor_values: [{}],
    additional_docs: '<string>',
    low_code: '<string>',
    rd_code: '<string>',
    hazardous: true,
    recycled: true
  })
};

fetch('https://api.dcycle.io/api/v1/custom_emission_factors/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/api/v1/custom_emission_factors/{id}"

payload = {
    "factor_uploaded_by": "<string>",
    "ef_name": "<string>",
    "emission_factor_values": [{}],
    "additional_docs": "<string>",
    "low_code": "<string>",
    "rd_code": "<string>",
    "hazardous": True,
    "recycled": True
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "x-user-id": "<x-user-id>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/api/v1/custom_emission_factors/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "factor_uploaded_by": "<string>",
  "ef_name": "<string>",
  "emission_factor_values": [
    {}
  ],
  "additional_docs": "<string>",
  "low_code": "<string>",
  "rd_code": "<string>",
  "hazardous": true,
  "recycled": true
}
'

Update Custom Emission Factor

Update specific fields of an existing custom emission factor. Only the fields provided in the request will be updated.

You cannot update the following fields: tag, uncertainty_grade, factor_start_date, factor_end_date, or unit_id. To change these, delete the factor and create a new one.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Path Parameters

string

required

UUID of the Custom Emission Factor to updateExample: "factor-uuid-here"

Body Parameters

All fields are optional - only include the fields you want to update.

string

required

Reference to person/team responsible for this updateExample: "sustainability_team@company.com"

string

Updated descriptive name for the emission factorExample: "Recycled Aluminum - Supplier ABC (Q2 2024)"

array

Updated emission values by gas type. Must match the factor’s tag:

Simple tag: Single co2e value
Advanced tag: All three values (CO2, CH4, N2O)

Example:

[
  {"gas_type": "CO2", "value": 2.25},
  {"gas_type": "CH4", "value": 0.009},
  {"gas_type": "N2O", "value": 0.0025}
]

string

Updated documentation reference or notesExample: "EPD No. ABC-2024-002, Updated Q2 2024"

string

For waste factors: Updated LER/LOW waste codeExample: "15 01 01"

string

For waste factors: Updated RD disposal method codeExample: "R3"

boolean

For waste factors: Updated hazardous statusExample: false

boolean

For waste/material factors: Updated recycled statusExample: true

Response

Returns the complete updated custom emission factor object.

Example

curl -X PATCH "https://api.dcycle.io/api/v1/custom_emission_factors/factor-uuid" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "factor_uploaded_by": "sustainability@company.com",
    "ef_name": "Recycled Aluminum - Supplier ABC (Updated Q2 2024)",
    "emission_factor_values": [
      {"gas_type": "CO2", "value": 2.25},
      {"gas_type": "CH4", "value": 0.009},
      {"gas_type": "N2O", "value": 0.0025}
    ],
    "additional_docs": "EPD No. ABC-2024-002, Updated with Q2 2024 data"
  }'

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "x-user-id": os.getenv("DCYCLE_USER_ID"),
    "Content-Type": "application/json"
}

factor_id = "factor-uuid"

update_data = {
    "factor_uploaded_by": "sustainability@company.com",
    "ef_name": "Recycled Aluminum - Supplier ABC (Updated Q2 2024)",
    "emission_factor_values": [
        {"gas_type": "CO2", "value": 2.25},
        {"gas_type": "CH4", "value": 0.009},
        {"gas_type": "N2O", "value": 0.0025}
    ],
    "additional_docs": "EPD No. ABC-2024-002, Updated with Q2 2024 data"
}

response = requests.patch(
    f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}",
    headers=headers,
    json=update_data
)

updated_factor = response.json()
print(f"✅ Updated: {updated_factor['ef_name']}")

const axios = require('axios');

const headers = {
  'Authorization': `Bearer ${process.env.DCYCLE_API_KEY}`,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'x-user-id': process.env.DCYCLE_USER_ID,
  'Content-Type': 'application/json'
};

const factorId = 'factor-uuid';

const updateData = {
  factor_uploaded_by: 'sustainability@company.com',
  ef_name: 'Recycled Aluminum - Supplier ABC (Updated Q2 2024)',
  emission_factor_values: [
    { gas_type: 'CO2', value: 2.25 },
    { gas_type: 'CH4', value: 0.009 },
    { gas_type: 'N2O', value: 0.0025 }
  ],
  additional_docs: 'EPD No. ABC-2024-002, Updated with Q2 2024 data'
};

axios.patch(
  `https://api.dcycle.io/api/v1/custom_emission_factors/${factorId}`,
  updateData,
  { headers }
)
.then(response => {
  const updatedFactor = response.data;
  console.log(`✅ Updated: ${updatedFactor.ef_name}`);
})
.catch(error => console.error(error));

Use Cases

Update Emission Values

When supplier provides updated EPD data:

# Get current factor first
current_factor = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}",
    headers=headers
).json()

# Update only the emission values
response = requests.patch(
    f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}",
    headers=headers,
    json={
        "factor_uploaded_by": "procurement@company.com",
        "emission_factor_values": [
            {"gas_type": "CO2", "value": 2.05},  # Improved process
            {"gas_type": "CH4", "value": 0.007},
            {"gas_type": "N2O", "value": 0.002}
        ],
        "additional_docs": f"{current_factor['additional_docs']} - Updated 2024-06-15"
    }
)

print(f"✅ Emission values updated")

Update Documentation Reference

Add audit trail information:

const factor = await axios.get(
  `https://api.dcycle.io/api/v1/custom_emission_factors/${factorId}`,
  { headers }
).then(res => res.data);

await axios.patch(
  `https://api.dcycle.io/api/v1/custom_emission_factors/${factorId}`,
  {
    factor_uploaded_by: 'audit_team@company.com',
    additional_docs: `${factor.additional_docs} | Third-party verified by SGS on 2024-06-20`
  },
  { headers }
);

Update Waste Codes

Correct waste classification codes:

requests.patch(
    f"https://api.dcycle.io/api/v1/custom_emission_factors/{waste_factor_id}",
    headers=headers,
    json={
        "factor_uploaded_by": "waste_manager@company.com",
        "low_code": "15 01 02",  # Corrected code
        "rd_code": "R4",
        "hazardous": False
    }
)

Common Errors

404 Not Found

Cause: Custom emission factor not found

{
  "detail": "Custom emission factor not found",
  "code": "NOT_FOUND"
}

Solution: Verify the factor ID exists.

422 Validation Error - Invalid Tag/Values Mismatch

Cause: The custom emission factor data custom emission factor values specified is invalid.

{
  "detail": "The custom emission factor data custom emission factor values specified is invalid.",
  "code": "VALIDATION_ERROR"
}

Solution: Ensure emission values match the factor’s tag:

Simple tag requires: [{"gas_type": "co2e", "value": X}]
Advanced tag requires: [{"gas_type": "CO2", ...}, {"gas_type": "CH4", ...}, {"gas_type": "N2O", ...}]

422 Validation Error - Negative Values

Cause: The custom emission factor value(s) specified is(are) invalid.

{
  "detail": "The custom emission factor value(s) specified is(are) invalid.",
  "code": "VALIDATION_ERROR"
}

Solution: Emission values must be non-negative (≥ 0).

Best Practices

1. Always Include Audit Trail

Document who made the change and why:

update_data = {
    "factor_uploaded_by": "sustainability_lead@company.com",
    "additional_docs": f"{current_docs} | Updated 2024-06-15 by Jane Doe - New supplier data"
}

2. Validate Before Updating

Fetch current factor first to understand its structure:

# Get current factor
current = requests.get(f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}", headers=headers).json()

# Only update if tag is 'advanced'
if current['tag'] == 'advanced':
    # Safe to update with 3-gas values
    requests.patch(url, headers=headers, json=update_data)

Keep additional_docs field up to date:

update_data = {
    "factor_uploaded_by": user_email,
    "emission_factor_values": new_values,
    "additional_docs": "EPD No. ABC-2024-002, Supersedes ABC-2024-001, Updated Q2 2024"
}

4. Cannot Update Immutable Fields

If you need to change tag, uncertainty_grade, unit_id, or validity dates:

Delete the existing factor
Create a new one with correct values

# Instead of trying to update unit_id (not allowed)
# Delete and recreate
requests.delete(f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}", headers=headers)
requests.post(f"https://api.dcycle.io/api/v1/custom_emission_factors/{group_id}", headers=headers, json=new_factor_data)

Get Factor

View current values

Delete Factor

Remove factor

Create Factor

Add new factor

Overview

Learn about custom factors

Get Custom Emission Factor Delete Custom Emission Factor

Introduction

Logistics

Facilities

Vehicles

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

Update Custom Emission Factor

Update Custom Emission Factor

Request

Headers

Path Parameters

Body Parameters

Response

Example

Use Cases

Update Emission Values

Update Documentation Reference

Update Waste Codes

Common Errors

404 Not Found

422 Validation Error - Invalid Tag/Values Mismatch

422 Validation Error - Negative Values

Best Practices

1. Always Include Audit Trail

2. Validate Before Updating

4. Cannot Update Immutable Fields

Get Factor

Delete Factor

Create Factor

Overview

​Update Custom Emission Factor

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Use Cases

​Update Emission Values

​Update Documentation Reference

​Update Waste Codes

​Common Errors

​404 Not Found

​422 Validation Error - Invalid Tag/Values Mismatch

​422 Validation Error - Negative Values

​Best Practices

​1. Always Include Audit Trail

​2. Validate Before Updating

​3. Update Related Documentation

​4. Cannot Update Immutable Fields

​Related Endpoints

Get Factor

Delete Factor

Create Factor

Overview

Update Custom Emission Factor

Request

Headers

Path Parameters

Body Parameters

Response

Example

Use Cases

Update Emission Values

Update Documentation Reference

Update Waste Codes

Common Errors

404 Not Found

422 Validation Error - Invalid Tag/Values Mismatch

422 Validation Error - Negative Values

Best Practices

1. Always Include Audit Trail

2. Validate Before Updating

3. Update Related Documentation

4. Cannot Update Immutable Fields

Related Endpoints