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

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

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

x-user-id

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.

factor_uploaded_by

string

required

Reference to person/team responsible for this updateExample: "[email protected]"

ef_name

string

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

emission_factor_values

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}
]

additional_docs

string

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

low_code

string

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

rd_code

string

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

hazardous

boolean

For waste factors: Updated hazardous statusExample: false

recycled

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": "[email protected]",
    "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"
  }'

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": "[email protected]",
        "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: '[email protected]',
    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": "[email protected]",
        "low_code": "15 01 02",  # Corrected code
        "rd_code": "R4",
        "hazardous": False
    }
)

Common Errors

404 Not Found

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

Solution: Verify the factor ID exists.

422 Validation Error - Invalid Tag/Values Mismatch

{
  "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

{
  "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": "[email protected]",
    "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

Introduction

Logistics

Facilities

Vehicles

Invoices

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

Introduction

Logistics

Facilities

Vehicles

Invoices

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

​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