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

# Update Custom Emission Factor

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

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

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

  **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-docs/custom-emission-factors/get">
    View current values
  </Card>

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

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

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