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

> Modify waste record details and update disposal information

# Update Waste

Update specific fields of an existing waste record. All fields are optional - only include fields you want to modify. Omitted fields will retain their current values.

<Note>
  **CO2e Recalculation**: When you update fields like `base_quantity`, `waste_efs_id`, or `unit_id`, CO2e emissions are automatically recalculated.
</Note>

## Request

### Path Parameters

<ParamField path="waste_id" type="uuid" required>
  The UUID of the waste record to update

  **Example:** `550e8400-e29b-41d4-a716-446655440000`
</ParamField>

### 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:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Body Parameters

All parameters are optional. Only include fields you want to update.

<ParamField body="identification_name" type="string">
  Waste identification name or invoice number

  **Example:** `"RSU-2024-001-Updated"`
</ParamField>

<ParamField body="description" type="string">
  Description of the waste

  **Example:** `"Updated description"`
</ParamField>

<ParamField body="start_date" type="date">
  Start date of the waste period. An empty string (`""`) is treated the same as omitting the field — the existing value is left unchanged.

  **Example:** `"2024-01-01"`
</ParamField>

<ParamField body="end_date" type="date">
  End date of the waste period. An empty string (`""`) is treated the same as omitting the field — the existing value is left unchanged.

  **Example:** `"2024-06-30"`
</ParamField>

<ParamField body="base_quantity" type="number">
  Waste quantity in the specified unit. Must be greater than 0.

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

<ParamField body="destination" type="string">
  Waste destination or treatment facility

  **Example:** `"New waste treatment plant"`
</ParamField>

<ParamField body="total_km_to_waste_center" type="number">
  Distance to waste treatment center in kilometers

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

<ParamField body="unit_id" type="uuid">
  UUID of the quantity unit

  **Example:** `"61743a63-ff70-459c-9567-5eee8f7dfd5c"`
</ParamField>

<ParamField body="waste_efs_id" type="uuid">
  UUID of the waste emission factor

  **Example:** `"770e8400-e29b-41d4-a716-446655440000"`
</ParamField>

<ParamField body="custom_emission_factor_id" type="uuid">
  UUID of a custom emission factor

  **Example:** `"880e8400-e29b-41d4-a716-446655440000"`
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier (UUID) for the waste record
</ResponseField>

<ResponseField name="identification_name" type="string">
  Waste identification name
</ResponseField>

<ResponseField name="description" type="string">
  Description of the waste
</ResponseField>

<ResponseField name="start_date" type="date">
  Start date of the waste period
</ResponseField>

<ResponseField name="end_date" type="date">
  End date of the waste period
</ResponseField>

<ResponseField name="base_quantity" type="number">
  Waste quantity in the original unit
</ResponseField>

<ResponseField name="quantity" type="number">
  Adjusted quantity after applying percentage allocation
</ResponseField>

<ResponseField name="percentage" type="number">
  Allocation percentage (0 to 1)
</ResponseField>

<ResponseField name="destination" type="string">
  Waste destination or treatment facility
</ResponseField>

<ResponseField name="total_km_to_waste_center" type="number">
  Distance to waste treatment center in km
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `uploaded`, `active`, `loading`, or `error`
</ResponseField>

<ResponseField name="error_messages" type="array[string] | null">
  Error details when status is `error`
</ResponseField>

<ResponseField name="co2e" type="number">
  CO2 equivalent emissions in kg CO2e
</ResponseField>

<ResponseField name="co2e_biomass" type="number">
  Biogenic CO2 emissions in kg CO2e
</ResponseField>

<ResponseField name="enabled" type="boolean | null">
  Whether the waste record is enabled for emission calculations
</ResponseField>

<ResponseField name="file_id" type="string | null">
  UUID of the linked file (if created via bulk import)
</ResponseField>

<ResponseField name="file_name" type="string | null">
  Name of the linked import file
</ResponseField>

<ResponseField name="file_url" type="string | null">
  Download URL for the linked file
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Timestamp when the record was created
</ResponseField>

<ResponseField name="updated_at" type="datetime | null">
  Timestamp when the record was last updated
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X PATCH "https://api.dcycle.io/v1/wastes/550e8400-e29b-41d4-a716-446655440000" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Content-Type: application/json" \
    -d '{
      "base_quantity": 2000.0,
      "description": "Updated municipal solid waste",
      "destination": "New waste treatment plant"
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  api_key = os.getenv("DCYCLE_API_KEY")
  org_id = os.getenv("DCYCLE_ORG_ID")
  waste_id = "550e8400-e29b-41d4-a716-446655440000"

  headers = {
      "x-api-key": api_key,
      "x-organization-id": org_id,
      "Content-Type": "application/json"
  }

  payload = {
      "base_quantity": 2000.0,
      "description": "Updated municipal solid waste",
      "destination": "New waste treatment plant"
  }

  response = requests.patch(
      f"https://api.dcycle.io/v1/wastes/{waste_id}",
      headers=headers,
      json=payload
  )

  waste = response.json()
  print(f"Waste updated: {waste['id']}")
  print(f"New quantity: {waste['base_quantity']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const apiKey = process.env.DCYCLE_API_KEY;
  const orgId = process.env.DCYCLE_ORG_ID;
  const wasteId = "550e8400-e29b-41d4-a716-446655440000";

  const headers = {
    'x-api-key': apiKey,
    'x-organization-id': orgId,
    'Content-Type': 'application/json'
  };

  const payload = {
    base_quantity: 2000.0,
    description: "Updated municipal solid waste",
    destination: "New waste treatment plant"
  };

  axios.patch(
    `https://api.dcycle.io/v1/wastes/${wasteId}`,
    payload,
    { headers }
  )
  .then(response => {
    const waste = response.data;
    console.log(`Waste updated: ${waste.id}`);
    console.log(`New quantity: ${waste.base_quantity}`);
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "identification_name": "RSU-2024-001",
  "description": "Updated municipal solid waste",
  "start_date": "2024-01-01",
  "end_date": "2024-03-31",
  "base_quantity": 2000.0,
  "quantity": 2000.0,
  "percentage": 1.0,
  "destination": "New waste treatment plant",
  "total_km_to_waste_center": 25.0,
  "status": "active",
  "error_messages": null,
  "co2e": 601.0,
  "co2e_biomass": 16.4,
  "enabled": true,
  "file_id": null,
  "file_name": null,
  "file_url": null,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T15:45:00Z"
}
```

## Common Errors

### 404 Not Found

**Cause:** Waste record not found in organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Waste with id=UUID('...') not found",
  "code": "WASTE_NOT_FOUND"
}
```

**Solution:** Verify the waste ID is correct and belongs to your organization.

### 403 Forbidden

**Cause:** Waste doesn't belong to your organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Waste doesn't belong to organization",
  "code": "FORBIDDEN"
}
```

**Solution:** Verify the `x-organization-id` header matches the organization that owns this waste record.

### 422 Validation Error

**Cause:** Invalid values

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["body", "base_quantity"],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt"
    }
  ]
}
```

**Solution:** Ensure numeric values are valid and within allowed ranges.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Wastes" icon="list" href="/api-reference/wastes/list">
    Retrieve all waste records
  </Card>

  <Card title="Create Waste" icon="plus" href="/api-reference/wastes/create">
    Add a new waste record
  </Card>

  <Card title="Facilities" icon="building" href="/api-reference/facilities/list">
    List facilities for your organization
  </Card>
</CardGroup>