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

# Update Custom Emission Factor

> Update an existing custom emission factor

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

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

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

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `ff4adcc7-8172-45fe-9cf1-e90a6de53aa9`
</ParamField>

<ParamField header="x-user-id" type="string" required>
  Your user UUID

  **Example:** `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  UUID of the Custom Emission Factor to update

  **Example:** `"factor-uuid-here"`
</ParamField>

### Body Parameters

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

<ParamField body="factor_uploaded_by" type="string" required>
  Reference to person/team responsible for this update

  **Example:** `"sustainability_team@company.com"`
</ParamField>

<ParamField body="ef_name" type="string">
  Updated descriptive name for the emission factor

  **Example:** `"Recycled Aluminum - Supplier ABC (Q2 2024)"`
</ParamField>

<ParamField body="emission_factor_values" type="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:**

  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  [
    {"gas_type": "CO2", "value": 2.25},
    {"gas_type": "CH4", "value": 0.009},
    {"gas_type": "N2O", "value": 0.0025}
  ]
  ```
</ParamField>

<ParamField body="additional_docs" type="string">
  Updated documentation reference or notes

  **Example:** `"EPD No. ABC-2024-002, Updated Q2 2024"`
</ParamField>

<ParamField body="low_code" type="string">
  For waste factors: Updated LER/LOW waste code

  Retrieve available options from [`GET /api/v1/wastes/low_codes`](/api-reference/legacy/wastes/codes) — `waste_region` is required; pass `GLO`

  **Example:** `"15 01 01"`
</ParamField>

<ParamField body="rd_code" type="string">
  For waste factors: Updated RD disposal method code

  Retrieve available options from [`GET /api/v1/wastes/rd_ler_list`](/api-reference/legacy/wastes/codes)

  **Example:** `"R3"`
</ParamField>

<ParamField body="hazardous" type="boolean">
  For waste factors: Updated hazardous status

  **Example:** `false`
</ParamField>

<ParamField body="recycled" type="boolean">
  For waste/material factors: Updated recycled status

  **Example:** `true`
</ParamField>

## Response

Returns the complete updated custom emission factor object.

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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));
  ```
</CodeGroup>

## Use Cases

### Update Emission Values

When supplier provides updated EPD data:

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

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

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

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

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

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

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

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

### 3. Update Related Documentation

Keep additional\_docs field up to date:

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

1. Delete the existing factor
2. Create a new one with correct values

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

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Factor" icon="magnifying-glass" href="/api-reference/legacy/custom-emission-factors/get">
    View current values
  </Card>

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

  <Card title="Create Factor" icon="plus" href="/api-reference/legacy/custom-emission-factors/create">
    Add new factor
  </Card>

  <Card title="Overview" icon="book" href="/api-reference/legacy/custom-emission-factors/overview">
    Learn about custom factors
  </Card>
</CardGroup>


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